libbladeRF  2.2.1
Nuand bladeRF library
Data Structures | Enumerations | Macros | Functions


The functions in this section provide the ability query and inspect available devices, initialize them, and deinitialize them.

See the Device configuration boilerplate page for an overview on how to open and configure a device.

These functions are thread-safe.

Data Structures

struct  bladerf_devinfo


enum  bladerf_backend {




API_EXPORT int CALL_CONV bladerf_open (struct bladerf **device, const char *device_identifier)
API_EXPORT void CALL_CONV bladerf_close (struct bladerf *device)
API_EXPORT int CALL_CONV bladerf_open_with_devinfo (struct bladerf **device, struct bladerf_devinfo *devinfo)
API_EXPORT int CALL_CONV bladerf_get_device_list (struct bladerf_devinfo **devices)
API_EXPORT void CALL_CONV bladerf_free_device_list (struct bladerf_devinfo *devices)
API_EXPORT void CALL_CONV bladerf_init_devinfo (struct bladerf_devinfo *info)
API_EXPORT int CALL_CONV bladerf_get_devinfo (struct bladerf *dev, struct bladerf_devinfo *info)
API_EXPORT int CALL_CONV bladerf_get_devinfo_from_str (const char *devstr, struct bladerf_devinfo *info)
API_EXPORT bool CALL_CONV bladerf_devinfo_matches (const struct bladerf_devinfo *a, const struct bladerf_devinfo *b)
API_EXPORT bool CALL_CONV bladerf_devstr_matches (const char *dev_str, struct bladerf_devinfo *info)
API_EXPORT const char *CALL_CONV bladerf_backend_str (bladerf_backend backend)
API_EXPORT void CALL_CONV bladerf_set_usb_reset_on_open (bool enabled)

Enumeration Type Documentation

◆ bladerf_backend

Backend by which the host communicates with the device


"Don't Care" – use any available backend


Linux kernel driver






Dummy used for development purposes

Definition at line 112 of file libbladeRF.h.

Macro Definition Documentation



Length of device description string, including NUL-terminator

Definition at line 122 of file libbladeRF.h.



Length of device serial number string, including NUL-terminator

Definition at line 125 of file libbladeRF.h.

Function Documentation

◆ bladerf_backend_str()

API_EXPORT const char* CALL_CONV bladerf_backend_str ( bladerf_backend  backend)

Retrieve the backend string associated with the specified backend enumeration value.

A string that can used to specify the backend portion of a device identifier string. (See bladerf_open().)

◆ bladerf_close()

API_EXPORT void CALL_CONV bladerf_close ( struct bladerf *  device)

Close device

Failing to close a device will result in memory leaks.
device is deallocated and may no longer be used.
deviceDevice handle previously obtained by bladerf_open(). This function does nothing if device is NULL.

◆ bladerf_devinfo_matches()

API_EXPORT bool CALL_CONV bladerf_devinfo_matches ( const struct bladerf_devinfo a,
const struct bladerf_devinfo b 

Test whether two device identifier information structures match, taking wildcard values into account.

[in]athe first bladerf_devinfo struct
[in]bthe second bladerf_devinfo struct

◆ bladerf_devstr_matches()

API_EXPORT bool CALL_CONV bladerf_devstr_matches ( const char *  dev_str,
struct bladerf_devinfo info 

Test whether a provided device string matches a device described by the provided bladerf_devinfo structure

[in]dev_strDevices string, formated as described in the the documentation of bladerf_open
[in]infoDevice info to compare with
true upon a match, false otherwise

◆ bladerf_free_device_list()

API_EXPORT void CALL_CONV bladerf_free_device_list ( struct bladerf_devinfo devices)

Free device list returned by bladerf_get_device_list()

[in,out]devicesList of available devices

◆ bladerf_get_device_list()

API_EXPORT int CALL_CONV bladerf_get_device_list ( struct bladerf_devinfo **  devices)

Obtain a list of bladeRF devices attached to the system

number of items in returned device list, or value from Error codes list on failure

◆ bladerf_get_devinfo()

API_EXPORT int CALL_CONV bladerf_get_devinfo ( struct bladerf *  dev,
struct bladerf_devinfo info 

Fill out a provided bladerf_devinfo structure, given an open device handle.

dev must be a valid device handle.
devDevice handle previously obtained with bladerf_open()
[out]infoDevice information populated by this function
0 on success, value from Error codes list on failure

◆ bladerf_get_devinfo_from_str()

API_EXPORT int CALL_CONV bladerf_get_devinfo_from_str ( const char *  devstr,
struct bladerf_devinfo info 

Populate a device identifier information structure using the provided device identifier string.

[in]devstrDevice identifier string, formated as described in the bladerf_open() documentation
[out]infoUpon success, this will be filled out according to the provided device identifier string, with wildcards for any fields that were not provided.
0 on success, value from Error codes list on failure

◆ bladerf_init_devinfo()

API_EXPORT void CALL_CONV bladerf_init_devinfo ( struct bladerf_devinfo info)

Initialize a device identifier information structure to a "wildcard" state.

The values in each field will match any value for that field.

Passing a bladerf_devinfo initialized with this function to bladerf_open_with_devinfo() will match the first device found.

◆ bladerf_open()

API_EXPORT int CALL_CONV bladerf_open ( struct bladerf **  device,
const char *  device_identifier 

Open specified device using a device identifier string. See bladerf_open_with_devinfo() if a device identifier string is not readily available.

The general form of the device identifier string is;

<backend>:[device=<bus>:<addr>] [instance=<n>] [serial=<serial>]

An empty ("") or NULL device identifier will result in the first encountered device being opened (using the first discovered backend)

The 'backend' describes the mechanism used to communicate with the device, and may be one of the following:

  • *: Any available backend
  • libusb: libusb (See libusb changelog notes for required version, given your OS and controller)
  • cypress: Cypress CyUSB/CyAPI backend (Windows only)

If no arguments are provided after the backend, the first encountered device on the specified backend will be opened. Note that a backend is required, if any arguments are to be provided.

Next, any provided arguments are provide as used to find the desired device. Be sure not to over constrain the search. Generally, only one of the above is required – providing all of these may over constrain the search for the desired device (e.g., if a serial number matches, but not on the specified bus and address.)

  • device=<bus>:<addr>
    • Specifies USB bus and address. Decimal or hex prefixed by '0x' is permitted.
  • instance=<n>
    • Nth instance encountered, 0-indexed
  • serial=<serial>
    • Device's serial number.

Below is an example of how to open a device with a specific serial number, using any avaiable backend supported by libbladeRF:

struct bladerf *dev;
int status = bladerf_open(&dev, "*:serial=f12ce1037830a1b27f3ceeba1f521413");
if (status != 0) {
fprintf(stderr, "Unable to open device: %s\n",
return status;
[out]deviceUpdate with device handle on success
[in]device_identifierDevice identifier, formatted as described above
0 on success, or value from Error codes list on failure

◆ bladerf_open_with_devinfo()

API_EXPORT int CALL_CONV bladerf_open_with_devinfo ( struct bladerf **  device,
struct bladerf_devinfo devinfo 

Opens device specified by provided bladerf_devinfo structure

This function is generally preferred over bladerf_open() when a device identifier string is not already provided.

The most common uses of this function are to:

Below is an example of how to use this function to open a device with a specific serial number:

struct bladerf *open_bladerf_from_serial(const char *serial)
int status;
struct bladerf *dev;
struct bladerf_devinfo info;
/* Initialize all fields to "don't care" wildcard values.
* Immediately passing this to bladerf_open_with_devinfo() would cause
* libbladeRF to open any device on any available backend. */
/* Specify the desired device's serial number, while leaving all other
* fields in the info structure wildcard values */
strncpy(info.serial, serial, BLADERF_SERIAL_LENGTH - 1);
info.serial[BLADERF_SERIAL_LENGTH - 1] = '\0';
status = bladerf_open_with_devinfo(&dev, &info);
if (status == BLADERF_ERR_NODEV) {
printf("No devices available with serial=%s\n", serial);
return NULL;
} else if (status != 0) {
fprintf(stderr, "Failed to open device with serial=%s (%s)\n", serial,
return NULL;
} else {
return dev;
[out]deviceUpdate with device handle on success
[in]devinfoDevice specification. If NULL, any available device will be opened.
0 on success, or value from Error codes list on failure

◆ bladerf_set_usb_reset_on_open()

API_EXPORT void CALL_CONV bladerf_set_usb_reset_on_open ( bool  enabled)

Enable or disable USB device reset operation upon opening a device for future bladerf_open() and bladerf_open_with_devinfo() calls.

This operation has been found to be necessary on Linux-based systems for some USB 3.0 controllers on Linux.

This does not reset the state of the device in terms of its frequency, gain, sample rate, etc. settings.

[in]enabledSet true to enable the use of the USB device reset, and false otherwise.