 |
libbladeRF
2.5.0
Nuand bladeRF library
|
|
libbladeRF
2.5.0
Nuand bladeRF library
|
This document describes many of the changes in libbladeRF 2.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.
We are very excited to release this library alongside the new bladeRF Micro. libbladeRF 2.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.
We attempted to minimize the changes required to make existing applications work with libbladeRF 2.0. 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.
Each topic has a table describing the affected functions, the importance of this change, and the recommended action. Please see Definitions for "Importance" for definitions of the words used in the "Importance" column.
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.
| API Component | Importance | Action |
|---|---|---|
| bladerf_get_frequency() | Required | The
|
| bladerf_set_frequency() | Required for full compatibility
| The
|
| bladerf_select_band() | ||
| bladerf_schedule_retune() |
UINT32_MAX. 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.
| API Component | Importance | Action |
|---|---|---|
| bladerf_sync_config() | Required | The Replace
|
| bladerf_stream() | ||
| bladerf_get_timestamp() | Optional | The Replace
|
| bladerf_set_stream_timeout() | ||
| bladerf_get_stream_timeout() | ||
| bladerf_sync_tx() | Informational | The samples parameter is now a pointer to a const, to enforce safety. This should not impact user code. |
BLADERF_MODULE_RX and BLADERF_MODULE_TX values. 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 Streaming API changes for MIMO section elsewhere in this document.
BLADERF_MODULE_RX or BLADERF_MODULE_TX. The precompiler constants for supported minimum/maximum values have been deprecated and replaced with a set of context-aware functions. The old constants will be removed in a later release.
| API Component | Importance | Action |
|---|---|---|
| BLADERF_RXVGA1_GAIN_MIN | Required for full compatibility
| Use bladerf_get_gain_stage_range() to retrieve the range of allowable gains for a specific gain stage.
|
| 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.
| |
| BLADERF_FREQUENCY_MIN | ||
| BLADERF_FREQUENCY_MAX |
An example use of bladerf_get_frequency_range():
BLADERF_*_{MIN,MAX} defines or any hardcoded values derived from them. bladerf_get_*_range() every time you need to know – don't cache it! Previously, the ranges used by bladerf_get_gain() and bladerf_set_gain() were somewhat arbitrary, with a value of 0 being the minimum possible gain, and the maximum possible gain being the sum of the max gain for all gain stages.
To allow the same gain settings to produce similar results on all bladeRF models, we've adjusted the gain ranges for these two functions to define 60 dB as the maximum available gain on RX, and roughly +0 dBm output power on TX.
| API Component | Importance | Action |
|---|---|---|
| bladerf_set_gain() | Required for full compatibility
| 60 dB is now defined as:
|
| bladerf_get_gain() |
For semantic clarity, common parameter types now have typedefs.
printf() with a bladerf_frequency or bladerf_timestamp currently require knowing that they are actually uint64_t, e.g. printf("the frequency is %" PRIu64 " Hz\n", freq);.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.
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).
The original manual gain control functionality in libbladeRF was 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 approaches described below.
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:
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.
Advanced implementations that need to directly configure the gain stages may use the following family of functions:
libbladeRF 2.0 includes support for new hardware features on the bladeRF Micro.
The bias tees apply a +5 VDC bias to the SMA connectors, which may be used for powering active antennas or inline amplifiers.
An external frequency reference may be connected to the J95 U.FL connector ("REFIN") to discipline the onboard VCTCXO. By default, this port expects 10 MHz, but it can be configured for reference frequencies between 5 MHz and 300 MHz.
Alternatively, a 38.4 MHz clock may be provided into the CLKIN port.
There is also a CLKOUT port, which can provide a buffered 38.4 MHz system clock output.
Functions are provided to determine how the board is currently being powered, what the bus voltage is, and what the system current and power draws are.
The RFIC has an onboard temperature sensor, which may be useful for environmental monitoring, or for determining if the RFIC's synthesizers should be re-tuned after a significant temperature shift.
In the bladeRF architecture, a channel is a single, unidirectional RF path. There is a 1:1 mapping between a bladerf_channel and a physical RF port.
On the original bladeRF, there are two channels available:
On the bladeRF Micro, there are four channels available:
Generally speaking, you will want to apply settings to a specific channel.
Note that some groups of channels may share some settings on some hardware: for example, if you bladerf_set_frequency() on a bladeRF Micro's BLADERF_CHANNEL_RX(0), it will also change the frequency of BLADERF_CHANNEL_RX(1), because both RX ports share the same local oscillator.
There are some functions which always apply to all the RX channels or all the TX channels. These accept a bladerf_direction argument:
Finally, there are two functions which accept a bladerf_channel_layout. This specifies two things: the direction (RX vs TX), and the number of channels interleaved in the sample buffers (currently 1 or 2).
| Word | Meaning |
|---|---|
| Required | This change must be performed to build code against libbladeRF 2.0. Compile errors will result if you fail to do so. |
| Required for full compatibility | This change is not required for building, but some functionality may be missing or unavailable with some devices. A Note will be included to describe the impact of not making this change. |
| Optional | This change is optional, but recommended for clarity and/or future compatibility. |
| Informational | This is an informational item, and no action is necessary or expected. |
1.9.1