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

Description

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
 

Enumerations

enum  bladerf_backend {
  BLADERF_BACKEND_ANY, BLADERF_BACKEND_LINUX, BLADERF_BACKEND_LIBUSB, BLADERF_BACKEND_CYPRESS,
  BLADERF_BACKEND_DUMMY = 100
}
 

Macros

#define BLADERF_DESCRIPTION_LENGTH   33
 
#define BLADERF_SERIAL_LENGTH   33
 

Functions

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

Enumerator
BLADERF_BACKEND_ANY 

"Don't Care" – use any available backend

BLADERF_BACKEND_LINUX 

Linux kernel driver

BLADERF_BACKEND_LIBUSB 

libusb

BLADERF_BACKEND_CYPRESS 

CyAPI

BLADERF_BACKEND_DUMMY 

Dummy used for development purposes

Definition at line 112 of file libbladeRF.h.

Macro Definition Documentation

◆ BLADERF_DESCRIPTION_LENGTH

#define BLADERF_DESCRIPTION_LENGTH   33

Length of device description string, including NUL-terminator

Definition at line 122 of file libbladeRF.h.

◆ BLADERF_SERIAL_LENGTH

#define BLADERF_SERIAL_LENGTH   33

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.

Returns
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

Note
Failing to close a device will result in memory leaks.
Postcondition
device is deallocated and may no longer be used.
Parameters
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.

Parameters
[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

Parameters
[in]dev_strDevices string, formated as described in the the documentation of bladerf_open
[in]infoDevice info to compare with
Returns
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()

Parameters
[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

Parameters
[out]devices
Returns
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.

Precondition
dev must be a valid device handle.
Parameters
devDevice handle previously obtained with bladerf_open()
[out]infoDevice information populated by this function
Returns
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.

Parameters
[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.
Returns
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.

Note
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",
bladerf_strerror(status));
return status;
}
Parameters
[out]deviceUpdate with device handle on success
[in]device_identifierDevice identifier, formatted as described above
Returns
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,
bladerf_strerror(status));
return NULL;
} else {
return dev;
}
}
Parameters
[out]deviceUpdate with device handle on success
[in]devinfoDevice specification. If NULL, any available device will be opened.
Returns
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.

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