libbladeRF: Initialization

| libbladeRF 2.2.1-git 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)
const API_EXPORT 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()

const API_EXPORT 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_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.

bladerf_strerror
const API_EXPORT char *CALL_CONV bladerf_strerror(int error)
BLADERF_SERIAL_LENGTH
#define BLADERF_SERIAL_LENGTH
Definition: libbladeRF.h:125
bladerf_devinfo::serial
char serial[BLADERF_SERIAL_LENGTH]
Definition: libbladeRF.h:133
BLADERF_ERR_NODEV
#define BLADERF_ERR_NODEV
Definition: libbladeRF.h:3995
bladerf_open_with_devinfo
API_EXPORT int CALL_CONV bladerf_open_with_devinfo(struct bladerf **device, struct bladerf_devinfo *devinfo)
bladerf_open
API_EXPORT int CALL_CONV bladerf_open(struct bladerf **device, const char *device_identifier)
bladerf_init_devinfo
API_EXPORT void CALL_CONV bladerf_init_devinfo(struct bladerf_devinfo *info)
bladerf_devinfo
Definition: libbladeRF.h:130