libhackrf
HackRF SDR platform library
|
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... | |
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.
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:
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
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.
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).
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
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 |
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. |
const char * hackrf_error_name | ( | enum hackrf_error | errcode | ) |
errcode | enum to convert |
int hackrf_exit | ( | ) |
Should be called before exit. No other libhackrf functions should be called after it. Can be safely called multiple times.
size_t hackrf_get_transfer_buffer_size | ( | hackrf_device * | device | ) |
[in] | device | unused |
uint32_t hackrf_get_transfer_queue_depth | ( | hackrf_device * | device | ) |
[in] | device | unused |
int hackrf_init | ( | ) |
Should be called before any other libhackrf function. Initializes libusb. Can be safely called multiple times.
const char * hackrf_library_release | ( | ) |
Can be called before hackrf_init
const char * hackrf_library_version | ( | ) |
Can be called before hackrf_init