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",
hackrf_error_name(result),
result);
return EXIT_FAILURE;
}
hackrf_init
int hackrf_init()
Initialize libhackrf.
hackrf_error_name
const char * hackrf_error_name(enum hackrf_error errcode)
Convert hackrf_error into human-readable string.
HACKRF_SUCCESS
@ 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 `free`d. 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

- hackrf_set_hw_sync_mode
- hackrf_init_sweep
- hackrf_set_operacake_ports
- hackrf_reset

## 0x0103

- hackrf_spiflash_status
- hackrf_spiflash_clear_status
- hackrf_set_operacake_ranges
- hackrf_set_operacake_freq_ranges
- hackrf_set_clkout_enable
- hackrf_operacake_gpio_test
- hackrf_cpld_checksum

## 0x0104

- hackrf_set_ui_enable
- hackrf_start_rx_sweep

## 0x0105

- hackrf_get_operacake_boards
- hackrf_set_operacake_mode
- hackrf_get_operacake_mode
- hackrf_set_operacake_dwell_times

## 0x0106

- hackrf_get_m0_state
- hackrf_set_tx_underrun_limit
- hackrf_set_rx_overrun_limit
- hackrf_get_clkin_status
- hackrf_board_rev_read
- hackrf_supported_platform_read

## 0x0107

- hackrf_set_leds

## Enumeration Type Documentation

## hackrf_error

enum 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

  errcode | enum 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] | device | unused

Returns
  size in bytes

## hackrf_get_transfer_queue_depth()

uint32_t hackrf_get_transfer_queue_depth | ( | hackrf_device * | device | ) |

Parameters

  [in] | device | unused

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