libhackrf
HackRF SDR platform library
|
Managing HackRF devices and querying information about them. More...
Data Structures | |
struct | read_partid_serialno_t |
MCU (LPC43xx) part ID and serial number. More... | |
struct | hackrf_bias_t_user_settting_req |
User settings for user-supplied bias tee defaults. More... | |
struct | hackrf_device_list_t |
List of connected HackRF devices. More... | |
Macros | |
#define | HACKRF_BOARD_REV_GSG (0x80) |
Made by GSG bit in hackrf_board_rev enum and in platform ID. More... | |
#define | HACKRF_PLATFORM_JAWBREAKER (1 << 0) |
JAWBREAKER platform bit in result of hackrf_supported_platform_read. More... | |
#define | HACKRF_PLATFORM_HACKRF1_OG (1 << 1) |
HACKRF ONE (pre r9) platform bit in result of hackrf_supported_platform_read. More... | |
#define | HACKRF_PLATFORM_RAD1O (1 << 2) |
RAD1O platform bit in result of hackrf_supported_platform_read. More... | |
#define | HACKRF_PLATFORM_HACKRF1_R9 (1 << 3) |
HACKRF ONE (r9 or later) platform bit in result of hackrf_supported_platform_read. More... | |
#define | BOARD_ID_HACKRF_ONE (BOARD_ID_HACKRF1_OG) |
These deprecated board ID names are provided for API compatibility. More... | |
#define | BOARD_ID_INVALID (BOARD_ID_UNDETECTED) |
These deprecated board ID names are provided for API compatibility. More... | |
Typedefs | |
typedef struct hackrf_device | hackrf_device |
Opaque struct for hackrf device info. More... | |
Enumerations | |
enum | hackrf_board_id { BOARD_ID_JELLYBEAN = 0 , BOARD_ID_JAWBREAKER = 1 , BOARD_ID_HACKRF1_OG = 2 , BOARD_ID_RAD1O = 3 , BOARD_ID_HACKRF1_R9 = 4 , BOARD_ID_UNRECOGNIZED = 0xFE , BOARD_ID_UNDETECTED = 0xFF } |
HACKRF board id enum. More... | |
enum | hackrf_board_rev { BOARD_REV_HACKRF1_OLD = 0 , BOARD_REV_HACKRF1_R6 = 1 , BOARD_REV_HACKRF1_R7 = 2 , BOARD_REV_HACKRF1_R8 = 3 , BOARD_REV_HACKRF1_R9 = 4 , BOARD_REV_HACKRF1_R10 = 5 , BOARD_REV_GSG_HACKRF1_R6 = 0x81 , BOARD_REV_GSG_HACKRF1_R7 = 0x82 , BOARD_REV_GSG_HACKRF1_R8 = 0x83 , BOARD_REV_GSG_HACKRF1_R9 = 0x84 , BOARD_REV_GSG_HACKRF1_R10 = 0x85 , BOARD_REV_UNRECOGNIZED = 0xFE , BOARD_REV_UNDETECTED = 0xFF } |
Board revision enum. More... | |
enum | hackrf_usb_board_id { USB_BOARD_ID_JAWBREAKER = 0x604B , USB_BOARD_ID_HACKRF_ONE = 0x6089 , USB_BOARD_ID_RAD1O = 0xCC15 , USB_BOARD_ID_INVALID = 0xFFFF } |
USB board ID (product ID) enum. More... | |
Functions | |
hackrf_device_list_t * | hackrf_device_list () |
List connected HackRF devices. More... | |
int | hackrf_device_list_open (hackrf_device_list_t *list, int idx, hackrf_device **device) |
Open a hackrf_device from a device list. More... | |
void | hackrf_device_list_free (hackrf_device_list_t *list) |
Free a previously allocated hackrf_device_list list. More... | |
int | hackrf_open (hackrf_device **device) |
Open first available HackRF device. More... | |
int | hackrf_open_by_serial (const char *const desired_serial_number, hackrf_device **device) |
Open HackRF device by serial number. More... | |
int | hackrf_close (hackrf_device *device) |
Close a previously opened device. More... | |
int | hackrf_board_id_read (hackrf_device *device, uint8_t *value) |
Read hackrf_board_id from a device. More... | |
int | hackrf_version_string_read (hackrf_device *device, char *version, uint8_t length) |
Read HackRF firmware version as a string. More... | |
int | hackrf_usb_api_version_read (hackrf_device *device, uint16_t *version) |
Read HackRF USB API version. More... | |
int | hackrf_board_partid_serialno_read (hackrf_device *device, read_partid_serialno_t *read_partid_serialno) |
Read board part ID and serial number. More... | |
const char * | hackrf_board_id_name (enum hackrf_board_id board_id) |
Convert hackrf_board_id into human-readable string. More... | |
uint32_t | hackrf_board_id_platform (enum hackrf_board_id board_id) |
Lookup platform ID (HACKRF_PLATFORM_xxx) from board id (hackrf_board_id) More... | |
const char * | hackrf_usb_board_id_name (enum hackrf_usb_board_id usb_board_id) |
Convert hackrf_usb_board_id into human-readable string. More... | |
int | hackrf_reset (hackrf_device *device) |
Reset HackRF device. More... | |
int | hackrf_set_ui_enable (hackrf_device *device, const uint8_t value) |
Enable / disable UI display (RAD1O, PortaPack, etc.) More... | |
int | hackrf_board_rev_read (hackrf_device *device, uint8_t *value) |
Read board revision of device. More... | |
const char * | hackrf_board_rev_name (enum hackrf_board_rev board_rev) |
Convert board revision name. More... | |
int | hackrf_supported_platform_read (hackrf_device *device, uint32_t *value) |
Read supported platform of device. More... | |
int | hackrf_set_leds (hackrf_device *device, const uint8_t state) |
Turn on or off (override) the LEDs of the HackRF device. More... | |
int | hackrf_set_user_bias_t_opts (hackrf_device *device, hackrf_bias_t_user_settting_req *req) |
Configure bias tee behavior of the HackRF device when changing RF states. More... | |
The libhackrf library interacts via HackRF hardware through a hackrf_device handle. This handle is opaque, meaning its fields are internal to the library and should not be accessed by user code. To use a device, it first needs to be opened, than it can be interacted with, and finally the device needs to be closed via hackrf_close.
hackrf_open opens the first USB device (chosen by libusb). Useful if only one HackRF device is expected to be present.
hackrf_open_by_serial opens a device by a given serial (suffix). If no serial is specified it defaults to hackrf_open
All connected HackRF devices can be listed via hackrf_device_list. The list must be freed by hackrf_device_list_free.
This struct lists all devices and their serial numbers. Any one of them can be opened by hackrf_device_list_open. All the fields should be treated read-only!
If the device is not needed anymore, then it can be closed via hackrf_close. Closing a device terminates all ongoing transfers, and resets the device to IDLE mode.
Board ID identifies the type of HackRF board connected. See the enum hackrf_board_id for possible values. The value can be read by hackrf_board_id_read and converted into a human-readable string using hackrf_board_id_name. When reading, the initial value of the enum should be BOARD_ID_UNDETECTED.
Version string identifies the firmware version on the board. It can be read with the function hackrf_version_string_read
USB API version identifies the USB API supported by the device's firmware. It is coded as a xx.xx 16-bit value, and can be read by hackrf_usb_api_version_read
Example of reading firmware and USB API version (from hackrf_info.c):
The part ID and serial number of the MCU. Read via hackrf_board_partid_serialno_read. See the documentation of the MCU for details.
Board revision identifies revision of the HackRF board inside a device. Read via hackrf_board_rev_read and converted into a human-readable string via hackrf_board_rev_name. See hackrf_board_rev for possible values. When reading, the value should be initialized with BOARD_REV_UNDETECTED
Identifies the platform supported by the firmare of the HackRF device. Read via hackrf_supported_platform_read. Returns a bitfield. Can identify bad firmware version on device.
#define BOARD_ID_HACKRF_ONE (BOARD_ID_HACKRF1_OG) |
#define BOARD_ID_INVALID (BOARD_ID_UNDETECTED) |
#define HACKRF_BOARD_REV_GSG (0x80) |
#define HACKRF_PLATFORM_HACKRF1_OG (1 << 1) |
#define HACKRF_PLATFORM_HACKRF1_R9 (1 << 3) |
#define HACKRF_PLATFORM_JAWBREAKER (1 << 0) |
#define HACKRF_PLATFORM_RAD1O (1 << 2) |
typedef struct hackrf_device hackrf_device |
Object can be created via hackrf_open, hackrf_device_list_open or hackrf_open_by_serial and be destroyed via hackrf_close
enum hackrf_board_id |
Returned by hackrf_board_id_read and can be converted to a human-readable string using hackrf_board_id_name
enum hackrf_board_rev |
Returned by hackrf_board_rev_read and can be converted into human-readable name by hackrf_board_rev_name. MSB (board_rev & HACKRF_BOARD_REV_GSG
) should signify if the board was built by GSG or not. hackrf_board_rev_name ignores this information.
enum hackrf_usb_board_id |
Contains USB-IF product id (field idProduct
in libusb_device_descriptor
). Can be used to identify general type of hardware. Only used in hackrf_device_list::usb_board_ids field of hackrf_device_list, and can be converted into human-readable string via hackrf_usb_board_id_name.
const char * hackrf_board_id_name | ( | enum hackrf_board_id | board_id | ) |
board_id | enum to convert |
uint32_t hackrf_board_id_platform | ( | enum hackrf_board_id | board_id | ) |
board_id | hackrf_board_id enum variant to convert |
int hackrf_board_id_read | ( | hackrf_device * | device, |
uint8_t * | value | ||
) |
The result can be converted into a human-readable string via hackrf_board_id_name
[in] | device | device to query |
[out] | value | hackrf_board_id enum value |
int hackrf_board_partid_serialno_read | ( | hackrf_device * | device, |
read_partid_serialno_t * | read_partid_serialno | ||
) |
Read MCU part id and serial number. See the documentation of the MCU for details!
[in] | device | device to query |
[out] | read_partid_serialno | result of query |
const char * hackrf_board_rev_name | ( | enum hackrf_board_rev | board_rev | ) |
board_rev | board revision enum from hackrf_board_rev_read |
int hackrf_board_rev_read | ( | hackrf_device * | device, |
uint8_t * | value | ||
) |
Requires USB API version 0x0106 or above!
[in] | device | device to read board revision from |
[out] | value | revision enum, will become one of hackrf_board_rev. Should be initialized with BOARD_REV_UNDETECTED |
int hackrf_close | ( | hackrf_device * | device | ) |
[in] | device | device to close |
hackrf_device_list_t * hackrf_device_list | ( | ) |
void hackrf_device_list_free | ( | hackrf_device_list_t * | list | ) |
[in] | list | list to free |
int hackrf_device_list_open | ( | hackrf_device_list_t * | list, |
int | idx, | ||
hackrf_device ** | device | ||
) |
[in] | list | device list to open device from |
[in] | idx | index of the device to open |
[out] | device | device handle to open |
int hackrf_open | ( | hackrf_device ** | device | ) |
[out] | device | device handle |
device
is NULL, HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other hackrf_error variant int hackrf_open_by_serial | ( | const char *const | desired_serial_number, |
hackrf_device ** | device | ||
) |
[in] | desired_serial_number | serial number of device to open. If NULL then default to first device found. |
[out] | device | device handle |
device
is NULL, HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other hackrf_error variant int hackrf_reset | ( | hackrf_device * | device | ) |
Requires USB API version 0x0102 or above!
device | device to reset |
int hackrf_set_leds | ( | hackrf_device * | device, |
const uint8_t | state | ||
) |
This function can turn on or off the LEDs of the device. There are 3 controllable LEDs on the HackRF one: USB, RX and TX. On the Rad1o, there are 4 LEDs. Each LED can be set individually, but the setting might get overridden by other functions.
The LEDs can be set via specifying them as bits of a 8 bit number state
, bit 0 representing the first (USB on the HackRF One) and bit 3 or 4 representing the last LED. The upper 4 or 5 bits are unused. For example, binary value 0bxxxxx101 turns on the USB and TX LEDs on the HackRF One.
Requires USB API version 0x0107 or above!
device | device to query |
state | LED states as a bitfield |
int hackrf_set_ui_enable | ( | hackrf_device * | device, |
const uint8_t | value | ||
) |
Enable or disable the display on display-enabled devices (Rad1o, PortaPack)
Requires USB API version 0x0104 or above!
device | device to enable/disable UI on |
value | Enable UI. Must be 1 or 0 |
int hackrf_set_user_bias_t_opts | ( | hackrf_device * | device, |
hackrf_bias_t_user_settting_req * | req | ||
) |
This function allows the user to configure bias tee behavior so that it can be turned on or off automatically by the HackRF when entering the RX, TX, or OFF state. By default, the HackRF switches off the bias tee when the RF path switches to OFF mode.
The bias tee configuration is specified via a bitfield:
0000000TmmRmmOmm
Where setting T/R/O bits indicates that the TX/RX/Off behavior should be set to mode 'mm', 0=don't modify
mm specifies the bias tee mode:
00 - do nothing 01 - reserved, do not use 10 - disable bias tee 11 - enable bias tee
device | device to configure |
state | Bias tee states, as a bitfield |
int hackrf_supported_platform_read | ( | hackrf_device * | device, |
uint32_t * | value | ||
) |
Returns a combination of HACKRF_PLATFORM_JAWBREAKER | HACKRF_PLATFORM_HACKRF1_OG | HACKRF_PLATFORM_RAD1O | HACKRF_PLATFORM_HACKRF1_R9
Requires USB API version 0x0106 or above!
[in] | device | device to query |
[out] | value | supported platform bitfield |
int hackrf_usb_api_version_read | ( | hackrf_device * | device, |
uint16_t * | version | ||
) |
Read version as MM.mm 16-bit value, where MM is the major and mm is the minor version, encoded as the hex digits of the 16-bit number.
Example code from hackrf_info.c
displaying the result:
[in] | device | device to query |
[out] | version | USB API version |
const char * hackrf_usb_board_id_name | ( | enum hackrf_usb_board_id | usb_board_id | ) |
usb_board_id | enum to convert |
int hackrf_version_string_read | ( | hackrf_device * | device, |
char * | version, | ||
uint8_t | length | ||
) |
[in] | device | device to query |
[out] | version | version string |
[in] | length | length of allocated string without null byte (so set it to length(arr)-1 ) |