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
struct	bladerf_backendinfo

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_backendinfo (struct bladerf *dev, struct bladerf_backendinfo *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

enum 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

device

Device 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]	a	the first bladerf_devinfo struct
[in]	b	the 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_str	Devices string, formated as described in the the documentation of bladerf_open
[in]	info	Device 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]

devices

List of available devices

bladerf_get_backendinfo()

API_EXPORT int CALL_CONV bladerf_get_backendinfo	(	struct bladerf *	dev,
		struct bladerf_backendinfo *	info
	)

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

Precondition

dev must be a valid device handle.

Parameters

	dev	Device handle previously obtained with bladerf_open()
[out]	info	Backend information populated by this function

Returns

0 on success, value from Error codes list on failure

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

	dev	Device handle previously obtained with bladerf_open()
[out]	info	Device 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]	devstr	Device identifier string, formated as described in the bladerf_open() documentation
[out]	info	Upon 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]	device	Update with device handle on success
[in]	device_identifier	Device 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:

• Open a device based upon the results of bladerf_get_device_list()
• Open a specific device based upon its serial number

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. */
 bladerf_init_devinfo(&info);
 
 /* 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]	device	Update with device handle on success
[in]	devinfo	Device 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]

enabled

Set true to enable the use of the USB device reset, and false otherwise.