libhackrf
HackRF SDR platform library
Enumerations | Functions
Library related functions and enums

Library initialization, exit, error handling, etc. More...

Enumerations

enum  hackrf_error {
  HACKRF_SUCCESS = 0 ,
  HACKRF_TRUE = 1 ,
  HACKRF_ERROR_INVALID_PARAM = -2 ,
  HACKRF_ERROR_NOT_FOUND = -5 ,
  HACKRF_ERROR_BUSY = -6 ,
  HACKRF_ERROR_NO_MEM = -11 ,
  HACKRF_ERROR_LIBUSB = -1000 ,
  HACKRF_ERROR_THREAD = -1001 ,
  HACKRF_ERROR_STREAMING_THREAD_ERR = -1002 ,
  HACKRF_ERROR_STREAMING_STOPPED = -1003 ,
  HACKRF_ERROR_STREAMING_EXIT_CALLED = -1004 ,
  HACKRF_ERROR_USB_API_VERSION = -1005 ,
  HACKRF_ERROR_NOT_LAST_DEVICE = -2000 ,
  HACKRF_ERROR_OTHER = -9999
}
 error enum, returned by many libhackrf functions More...
 

Functions

int hackrf_init ()
 Initialize libhackrf. More...
 
int hackrf_exit ()
 Exit libhackrf. More...
 
const char * hackrf_library_version ()
 Get library version. More...
 
const char * hackrf_library_release ()
 Get library release. More...
 
const char * hackrf_error_name (enum hackrf_error errcode)
 Convert hackrf_error into human-readable string. More...
 
size_t hackrf_get_transfer_buffer_size (hackrf_device *device)
 Get USB transfer buffer size. More...
 
uint32_t hackrf_get_transfer_queue_depth (hackrf_device *device)
 Get the total number of USB transfer buffers. More...
 

Detailed Description

Library initialization & exit

The libhackrf library needs to be initialized in order to use most of its functions. This can be achieved via the function hackrf_init. This initializes internal state and initializes libusb. You should only call this function on startup, but it's safe to call it later as well, only it does nothing.

When exiting the program, a call to hackrf_exit should be called. This releases all resources, stops background thread and exits libusb. This function should only be called if all streaming is stopped and all devices are closed via hackrf_close, else the error HACKRF_ERROR_NOT_LAST_DEVICE is returned.

Error handling

Many of the functions in libhackrf can signal errors via returning hackrf_error. This enum is backed by an integer, thus these functions are declared to return an int, but they in fact return an enum variant. The special case HACKRF_SUCCESS signals no errors, so return values should be matched for that. It is also set to the value 0, so boolean conversion can also be used. The function hackrf_error_name can be used to convert the enum into a human-readable string, useful for logging the error.

There is a special variant HACKRF_TRUE, used by some functions that return boolean. This fact is explicitly mentioned at those functions.

Typical error-handling code example:

result = hackrf_init();
if (result != HACKRF_SUCCESS) {
fprintf(stderr,
"hackrf_init() failed: %s (%d)\n",
result);
return EXIT_FAILURE;
}
int hackrf_init()
Initialize libhackrf.
const char * hackrf_error_name(enum hackrf_error errcode)
Convert hackrf_error into human-readable string.
@ HACKRF_SUCCESS
no error happened
Definition: hackrf.h:560

Instead of if (result != HACKRF_SUCCESS) the line if (result) can also be used with the exact same behaviour.

The special case HACKRF_TRUE is only used by hackrf_is_streaming

Enum conversion

Most of the enums defined in libhackrf have a corresponding _name function that converts the enum value into a human-readable string. All strings returned by these functions are statically allocated and do not need to be freed. An example is the already mentioned hackrf_error_name function for the hackrf_error enum.

Library internals

The library uses libusb (version 1.0) to communicate with HackRF hardware. It uses both the synchronous and asynchronous API for communication (asynchronous for streaming data to/from the device, and synchronous for everything else). The asynchronous API requires to periodically call a variant of libusb_handle_events, so the library creates a new "transfer thread" for each device doing that using the pthread library. The library uses multiple transfers for each device (hackrf_get_transfer_queue_depth).

USB API versions

As all functionality of HackRF devices requires cooperation between the firmware and the host, both devices can have outdated software. If host machine software is outdated, the new functions will be unalaviable in hackrf.h, causing linking errors. If the device firmware is outdated, the functions will return HACKRF_ERROR_USB_API_VERSION. Since device firmware and USB API are separate (but closely related), USB API has its own version numbers. Here is a list of all the functions that require a certain minimum USB API version, up to version 0x0107

0x0102

0x0103

0x0104

0x0105

0x0106

0x0107

Enumeration Type Documentation

◆ hackrf_error

Many functions that are specified to return INT are actually returning this enum

Enumerator
HACKRF_SUCCESS 

no error happened

HACKRF_TRUE 

TRUE value, returned by some functions that return boolean value.

Only a few functions can return this variant, and this fact should be explicitly noted at those functions.

HACKRF_ERROR_INVALID_PARAM 

The function was called with invalid parameters.

HACKRF_ERROR_NOT_FOUND 

USB device not found, returned at opening.

HACKRF_ERROR_BUSY 

Resource is busy, possibly the device is already opened.

HACKRF_ERROR_NO_MEM 

Memory allocation (on host side) failed.

HACKRF_ERROR_LIBUSB 

LibUSB error, use hackrf_error_name to get a human-readable error string (using libusb_strerror)

HACKRF_ERROR_THREAD 

Error setting up transfer thread (pthread-related error)

HACKRF_ERROR_STREAMING_THREAD_ERR 

Streaming thread could not start due to an error.

HACKRF_ERROR_STREAMING_STOPPED 

Streaming thread stopped due to an error.

HACKRF_ERROR_STREAMING_EXIT_CALLED 

Streaming thread exited (normally)

HACKRF_ERROR_USB_API_VERSION 

The installed firmware does not support this function.

HACKRF_ERROR_NOT_LAST_DEVICE 

Can not exit library as one or more HackRFs still in use.

HACKRF_ERROR_OTHER 

Unspecified error.

Function Documentation

◆ hackrf_error_name()

const char * hackrf_error_name ( enum hackrf_error  errcode)
Parameters
errcodeenum to convert
Returns
human-readable name of error

◆ hackrf_exit()

int hackrf_exit ( )

Should be called before exit. No other libhackrf functions should be called after it. Can be safely called multiple times.

Returns
HACKRF_SUCCESS on success or HACKRF_ERROR_NOT_LAST_DEVICE if not all devices were closed properly.

◆ hackrf_get_transfer_buffer_size()

size_t hackrf_get_transfer_buffer_size ( hackrf_device device)
Parameters
[in]deviceunused
Returns
size in bytes

◆ hackrf_get_transfer_queue_depth()

uint32_t hackrf_get_transfer_queue_depth ( hackrf_device device)
Parameters
[in]deviceunused
Returns
number of buffers

◆ hackrf_init()

int hackrf_init ( )

Should be called before any other libhackrf function. Initializes libusb. Can be safely called multiple times.

Returns
HACKRF_SUCCESS on success or HACKRF_ERROR_LIBUSB

◆ hackrf_library_release()

const char * hackrf_library_release ( )

Can be called before hackrf_init

Returns
library version as a human-readable string.

◆ hackrf_library_version()

const char * hackrf_library_version ( )

Can be called before hackrf_init

Returns
library version as a human-readable string