My Project
libbladeRF 2.0.0 Release Notes

Table of Contents

This page describes many of the changes in libbladeRF 2.0.0, our latest major version increment that features significant changes. This release adds support for the bladeRF 2.0 Micro, and improves the API for all bladeRF products. This is also the first release with bindings for the Python programming language.

Attention
libbladeRF 2.0.0 introduces breaking changes to the parameter lists for bladerf_get_frequency(), bladerf_stream(), and bladerf_sync_config().
Existing code using these functions must be updated to be compatible with this version. See the Tuning frequencies are now uint64_t and MIMO support in streaming API sections for guidance.

We are very excited to release this library alongside the new bladeRF Micro. libbladeRF 2.0.0 began as a fork of the bladeRF codebase. Across the FPGA, firmware, and host software trees, we added 95,000+ lines (and deleted 18,000+) to the bladeRF codebase, in more than 600 commits.

In case you experience any bugs or missing features, please use our issue tracker at https://github.com/Nuand/bladeRF/issues to report any problems you encounter with this release. Also, visit our forums at https://nuand.com/forums/ to discuss this release with other bladeRF users.

Significant changes to the libbladeRF API

We attempted to minimize the changes required to make existing applications work with libbladeRF 2.x. However, the nature of this project required some changes to the API.

Many of the changes can be transparently handled by compilers. However, applications will generally need to be recompiled and relinked to work with this version.

Tuning frequencies are now uint64_t

In libbladeRF 1.x, RF frequencies were specified as 32-bit unsigned int. To support the wider frequency range of the bladeRF Micro, frequencies are now specified as uint64_t, which is typedef'd as bladerf_frequency.

Required actions
API ComponentImportanceAction
bladerf_get_frequency() Required

The frequency parameter is now of type bladerf_frequency*.

Warning
Applications using this function must be modified to pass in the correct type.
bladerf_set_frequency() Minor

The frequency parameter is now of type bladerf_frequency.

Note
Compilers will generally implicitly cast unsigned int to bladerf_frequency.
bladerf_select_band()
bladerf_schedule_retune()

MIMO support in streaming API

The data transfer APIs were expanded to support MIMO (multiple-input, multiple-output). This capability is used to transmit or receive samples via multiple RF ports simultaneously.

Required actions
API ComponentImportanceAction
bladerf_sync_config() Required

The bladerf_module argument has been replaced with bladerf_channel_layout.

Replace BLADERF_MODULE_RX with BLADERF_RX_X1, and BLADERF_MODULE_TX with BLADERF_TX_X1.

Warning
Applications using these functions must be modified to pass in the correct type.
Note
Existing bladerf_module values are valid for SISO applications, but an explicit cast is required:
void configure_module_sync(bladerf_module module) {
// ...
status = bladerf_sync_config(dev, (bladerf_channel_layout)module, format, num_buffers, buffer_size, num_transfers, stream_timeout);
// ...
}
bladerf_stream()
bladerf_get_timestamp() Minor

The bladerf_module argument has been replaced with bladerf_direction.

Replace BLADERF_MODULE_RX with BLADERF_RX, and BLADERF_MODULE_TX with BLADERF_TX.

Note
Existing bladerf_module values are still valid, and a cast should not be necessary.
bladerf_set_stream_timeout()
bladerf_get_stream_timeout()
bladerf_sync_tx()

The samples parameter is now a pointer to a const.

This should not impact user code.

See also
BLADERF_FORMAT_SC16_Q11 describes the sample interleaving format.
bladerf_interleave_stream_buffer() - Interleaves contiguous blocks of samples in preparation for MIMO TX.
bladerf_deinterleave_stream_buffer() - Deinterleaves samples into contiguous blocks after MIMO RX.
bladerf_get_channel_count() - Get the number of RX or TX channels supported by the given device.

bladerf_channel replaces bladerf_module

In libbladeRF 1.x, bladerf_module was an enum with two valid choices: BLADERF_MODULE_RX and BLADERF_MODULE_TX. To support MIMO, this enum has been replaced with bladerf_channel, and a pair of convenience macros have been defined to specify channels: BLADERF_CHANNEL_RX(ch) and BLADERF_CHANNEL_TX(ch).

For backwards compatibility, bladerf_module is a typedef of bladerf_channel, and the BLADERF_MODULE_RX and BLADERF_MODULE_TX identifiers are now macros for BLADERF_CHANNEL_RX(0) and BLADERF_CHANNEL_TX(0) respectively.

Note that some bladerf_module instances have been replaced with bladerf_direction and bladerf_channel_layout depending on context. See the api_stream section elsewhere in this document.

Required actions
API ComponentImportanceAction
bladerf_enable_module() Required for MIMO support, optional otherwise

Replace bladerf_module with bladerf_channel.

Replace BLADERF_MODULE_RX with BLADERF_CHANNEL_RX(0), or generally, BLADERF_CHANNEL_RX(channel_number)

Replace BLADERF_MODULE_TX with BLADERF_CHANNEL_TX(0), or generally, BLADERF_CHANNEL_TX(channel_number)

bladerf_set_gain()
bladerf_set_gain_mode()
bladerf_get_gain_mode()
bladerf_set_sample_rate()
bladerf_set_rational_sample_rate()
bladerf_get_sample_rate()
bladerf_get_rational_sample_rate()
bladerf_set_bandwidth()
bladerf_get_bandwidth()
bladerf_set_lpf_mode()
bladerf_get_lpf_mode()
bladerf_select_band()
bladerf_set_frequency()
bladerf_schedule_retune()
bladerf_cancel_scheduled_retunes()
bladerf_get_frequency()
bladerf_get_quick_tune()
bladerf_trigger_init()
bladerf_set_correction()
bladerf_get_correction()
bladerf_xb200_set_filterbank()
bladerf_xb200_get_filterbank()
bladerf_xb200_set_path()
bladerf_xb200_get_path()
bladerf_read_trigger()
bladerf_write_trigger()
See also
bladerf_get_channel_count() - Get the number of RX or TX channels supported by the given device.

bladerf_get_*_range functions replace #define'd constants

The #define'd constants for supported minimum/maximum values have been deprecated and replaced with a set of context-aware functions.

Required actions
API ComponentImportanceAction
BLADERF_RXVGA1_GAIN_MIN Required for complete bladeRF Micro compatibility Use bladerf_get_gain_stage_range() to retrieve the range of allowable gains for a specific gain stage. This should be called after setting the frequency with bladerf_set_frequency().
BLADERF_RXVGA1_GAIN_MAX
BLADERF_RXVGA2_GAIN_MIN
BLADERF_RXVGA2_GAIN_MAX
BLADERF_TXVGA1_GAIN_MIN
BLADERF_TXVGA1_GAIN_MAX
BLADERF_TXVGA2_GAIN_MIN
BLADERF_TXVGA2_GAIN_MAX
BLADERF_LNA_GAIN_MID_DB
BLADERF_LNA_GAIN_MAX_DB
BLADERF_SAMPLERATE_MIN Use bladerf_get_sample_rate_range() to retrieve the range of allowable sample rates for a given channel.
BLADERF_SAMPLERATE_REC_MAX
BLADERF_BANDWIDTH_MIN Use bladerf_get_bandwidth_range() to retrieve the supported range of bandwidths for a given channel.
BLADERF_BANDWIDTH_MAX
BLADERF_FREQUENCY_MIN_XB200

Use bladerf_get_frequency_range() to retrieve the supported range of frequencies for a given channel.

Note
This will vary depending on the particular hardware configuration (such as if a XB-200 is attached).
BLADERF_FREQUENCY_MIN
BLADERF_FREQUENCY_MAX

An example use of bladerf_get_frequency_range():

bool is_frequency_within_range(struct bladerf *dev, bladerf_channel channel, bladerf_frequency frequency)
{
int status;
struct bladerf_range range;
status = bladerf_get_frequency_range(dev, channel, &range);
if (status < 0) {
// error case
}
return ((frequency / range.scale) >= range.min && (frequency / range.scale) <= range.max);
}
See also
bladerf_get_gain_stages() - Get a list of available gain stages.
bladerf_set_gain() - Set overall system gain.
bladerf_get_gain() - Get overall system gain.

New type definitions for parameters

The following types are now defined:

With the exception of ::bladerf_frequency, none of the underlying types changed from libbladeRF 1.x.x and no changes are strictly necessary. However, the declarations changed for the following functions:

As well as:

New features

Multiple platform support

We reorganized libbladeRF to easily support multiple hardware platforms. You will find a new directory tree, host/libraries/libbladeRF/src/board/, containing subdirectories for each supported platform (currently bladerf1/ for the LMS6002D-based bladeRF family, and bladerf2/ for the AD9361-based bladeRF Micro family).

Likewise, product-specific API calls have been moved into two new header files: bladeRF1.h and bladeRF2.h. Functions which apply to all boards remain in libbladeRF.h.

See also
Refer to bladeRF1.h and bladeRF2.h for a list of affected functions.
Note
Using API calls specified in bladeRF1.h or bladeRF2.h is not recommended for most use cases. They are provided for backwards compatibility and low-level hardware control, and are subject to change.

We also rearranged a number of source files into subdirectories of host/libraries/libbladeRF/src/. In addition to the pre-existing backend/, you'll also find board/ (product-specific code), driver/ (device drivers), expansion/ (expansion board drivers), helpers/ (helpful utility functions), and streaming/ (sample streaming code).

Gain control improvements

The original manual gain control functionality in libbladeRF is very low-level and hardware-specific, and requires significant knowledge of the underlying RF module to adjust. As such, new gain control methods have been introduced to the API, and the following functions are now deprecated:

Instead, applications should use one of the following approaches:

Automatic Gain Control (AGC)

Automatic gain control is available for RX channels, starting with libbladeRF v1.9.0 and FPGA v0.7.0. AGC continually adjusts the system's gain to ensure the received signal has a high dynamic range, while avoiding clipping.

As of this writing, the available gain modes are:

Note
bladerf_get_gain_mode() and bladerf_set_gain_mode() will return ::BLADERF_ERR_UNSUPPORTED for TX channels.
void agc_example(struct bladerf *dev, bladerf_channel channel)
{
int i, status;
const struct bladerf_gain_modes *modes = NULL;
bladerf_gain_mode mode;
// What gain modes are available?
status = bladerf_get_gain_modes(dev, channel, &modes);
if (status < 0) {
// error case
}
for (i = 0; i < status; ++i) {
printf("enum %d is gain mode %s\n", modes[i]->mode, modes[i]->name);
}
// Get current gain mode
status = bladerf_get_gain_mode(dev, channel, &mode);
if (status < 0) {
// error case
}
printf("current gain mode: %d\n", mode);
// Enable AGC
mode = BLADERF_GAIN_AUTOMATIC;
status = bladerf_set_gain_mode(dev, channel, mode);
if (status < 0) {
// error case
}
}

System gain proportioning

In previous versions, setting the gain required careful proportioning of gain between LNAs and VGAs. To reduce the implementation burden, an overall gain may now be specified, and the RFIC's gain stages will be set appropriately.

The gain scales are defined such that a 60 dB gain on a TX channel is approximately 0 dBm CW output, and a 60 dB gain on a RX channel is the maximum available amplification.

Note
bladerf_set_gain() may be unavailable or may not operate as expected if Automatic Gain Control (AGC) is enabled, or if the channel is not currently enabled.
The range returned by bladerf_get_gain_range() may vary depending on the selected center frequency.
void gain_example(struct bladerf *dev, bladerf_channel channel, int gain)
{
int old_gain, status;
const struct bladerf_range *range = NULL;
// What is the valid range?
status = bladerf_get_gain_range(dev, channel, &range);
if (status < 0) {
// error case
}
// What is the current gain?
status = bladerf_get_gain(dev, channel, &old_gain);
if (status < 0) {
// error case
};
printf("Channel %d current gain: %4d dB (Range: [%g, %g])\n",
channel, old_gain, range->min * range->scale, range->max * range->scale);
// Set the new gain value
status = bladerf_set_gain(dev, channel, gain);
if (status < 0) {
// error case
};
}
...
gain_example(dev, BLADERF_CHANNEL_TX(0), 60); // set 60 dB TX gain (~ 0 dBm)
gain_example(dev, BLADERF_CHANNEL_RX(0), 60); // set 60 dB RX gain (max)

Individual gain stage control

Advanced implementations that need to directly configure the gain stages may use the following family of functions:

Note
The values set here will be reflected in bladerf_get_gain(), but using bladerf_set_gain() will override any individual gain stage settings on a particular channel.
bladerf_set_gain_stage() may be unavailable or may not operate as expected if Automatic Gain Control (AGC) is enabled, or if the channel is not currently enabled.
The range returned by bladerf_get_gain_stage_range() may vary depending on the selected center frequency.

MIMO

Python bindings