libhackrf: Device listing, opening, closing and querying

libhackrf HackRF SDR platform library

Data Structures | Macros | Typedefs | Enumerations | Functions
Device listing, opening, closing and querying

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...

## Detailed Description

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.

# Opening devices

## Open first device

hackrf_open opens the first USB device (chosen by libusb). Useful if only one HackRF device is expected to be present.

## Open by serial

hackrf_open_by_serial opens a device by a given serial (suffix). If no serial is specified it defaults to hackrf_open

## Open by listing

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!

# Closing devices

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.

# Querying device information

## Board ID

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

Version string identifies the firmware version on the board. It can be read with the function hackrf_version_string_read

## USB API version

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):

result = hackrf_version_string_read(device, &version[0], 255);
if (result != HACKRF_SUCCESS) {
fprintf(stderr,
"hackrf_version_string_read() failed: %s (%d)\n",
hackrf_error_name(result),
result);
return EXIT_FAILURE;
}
result = hackrf_usb_api_version_read(device, &usb_version);
if (result != HACKRF_SUCCESS) {
fprintf(stderr,
"hackrf_usb_api_version_read() failed: %s (%d)\n",
hackrf_error_name(result),
result);
return EXIT_FAILURE;
}
printf("Firmware Version: %s (API:%x.%02x)\n",
version,
(usb_version >> 8) & 0xFF,
usb_version & 0xFF);
hackrf_version_string_read
int hackrf_version_string_read(hackrf_device *device, char *version, uint8_t length)
Read HackRF firmware version as a string.
hackrf_usb_api_version_read
int hackrf_usb_api_version_read(hackrf_device *device, uint16_t *version)
Read HackRF USB API version.
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

## Part ID and serial number

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

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

## Supported platform

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.

## Macro Definition Documentation

## ◆ BOARD_ID_HACKRF_ONE

#define BOARD_ID_HACKRF_ONE (BOARD_ID_HACKRF1_OG)

## ◆ BOARD_ID_INVALID

#define BOARD_ID_INVALID (BOARD_ID_UNDETECTED)

## ◆ HACKRF_BOARD_REV_GSG

#define HACKRF_BOARD_REV_GSG (0x80)

## ◆ HACKRF_PLATFORM_HACKRF1_OG

#define HACKRF_PLATFORM_HACKRF1_OG (1 << 1)

## ◆ HACKRF_PLATFORM_HACKRF1_R9

#define HACKRF_PLATFORM_HACKRF1_R9 (1 << 3)

## ◆ HACKRF_PLATFORM_JAWBREAKER

#define HACKRF_PLATFORM_JAWBREAKER (1 << 0)

## ◆ HACKRF_PLATFORM_RAD1O

#define HACKRF_PLATFORM_RAD1O (1 << 2)

## Typedef Documentation

## ◆ hackrf_device

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

## Enumeration Type Documentation

## ◆ hackrf_board_id

enum hackrf_board_id

Returned by hackrf_board_id_read and can be converted to a human-readable string using hackrf_board_id_name

Enumerator
BOARD_ID_JELLYBEAN | Jellybean (pre-production revision, not supported)
BOARD_ID_JAWBREAKER | Jawbreaker (beta platform, 10-6000MHz, no bias-tee)
BOARD_ID_HACKRF1_OG | HackRF One (prior to rev 9, same limits: 1-6000MHz, 20MSPS, bias-tee)
BOARD_ID_RAD1O | RAD1O (Chaos Computer Club special edition with LCD & other features. 50M-4000MHz, 20MSPS, no bias-tee)
BOARD_ID_HACKRF1_R9 | HackRF One (rev. 9 & later. 1-6000MHz, 20MSPS, bias-tee)
BOARD_ID_UNRECOGNIZED | Unknown board (failed detection)
BOARD_ID_UNDETECTED | Unknown board (detection not yet attempted, should be default value)

## ◆ hackrf_board_rev

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.

Enumerator
BOARD_REV_HACKRF1_OLD | Older than rev6.
BOARD_REV_HACKRF1_R6 | board revision 6, generic
BOARD_REV_HACKRF1_R7 | board revision 7, generic
BOARD_REV_HACKRF1_R8 | board revision 8, generic
BOARD_REV_HACKRF1_R9 | board revision 9, generic
BOARD_REV_HACKRF1_R10 | board revision 10, generic
BOARD_REV_GSG_HACKRF1_R6 | board revision 6, made by GSG
BOARD_REV_GSG_HACKRF1_R7 | board revision 7, made by GSG
BOARD_REV_GSG_HACKRF1_R8 | board revision 8, made by GSG
BOARD_REV_GSG_HACKRF1_R9 | board revision 9, made by GSG
BOARD_REV_GSG_HACKRF1_R10 | board revision 10, made by GSG
BOARD_REV_UNRECOGNIZED | unknown board revision (detection failed)
BOARD_REV_UNDETECTED | unknown board revision (detection not yet attempted)

## ◆ hackrf_usb_board_id

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.

Enumerator
USB_BOARD_ID_JAWBREAKER | Jawbreaker (beta platform) USB product id.
USB_BOARD_ID_HACKRF_ONE | HackRF One USB product id.
USB_BOARD_ID_RAD1O | RAD1O (custom version) USB product id.
USB_BOARD_ID_INVALID | Invalid / unknown USB product id.

## Function Documentation

## ◆ hackrf_board_id_name()

const char * hackrf_board_id_name | ( | enum hackrf_board_id | board_id | ) |

Parameters

  board_id | enum to convert

Returns
  human-readable name of board id

## ◆ hackrf_board_id_platform()

uint32_t hackrf_board_id_platform | ( | enum hackrf_board_id | board_id | ) |

Parameters

  board_id | hackrf_board_id enum variant to convert

Returns
  HACKRF_PLATFORM_JAWBREAKER, HACKRF_PLATFORM_HACKRF1_OG, HACKRF_PLATFORM_RAD1O, HACKRF_PLATFORM_HACKRF1_R9 or 0

## ◆ hackrf_board_id_read()

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

Parameters

  [in] | device | device to query
  [out] | value | hackrf_board_id enum value

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_board_partid_serialno_read()

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!

Parameters

  [in] | device | device to query
  [out] | read_partid_serialno | result of query

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_board_rev_name()

const char * hackrf_board_rev_name | ( | enum hackrf_board_rev | board_rev | ) |

Parameters

  board_rev | board revision enum from hackrf_board_rev_read

Returns
  human-readable name of board revision. Discards GSG bit.

## ◆ hackrf_board_rev_read()

int hackrf_board_rev_read | ( | hackrf_device * | device,
|  | uint8_t * | value
| ) |  |

Requires USB API version 0x0106 or above!

Parameters

  [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

Returns
  HACKRF_SUCCESS on success or HACKRF_ERROR_LIBUSB

## ◆ hackrf_close()

int hackrf_close | ( | hackrf_device * | device | ) |

Parameters

  [in] | device | device to close

Returns
  HACKRF_SUCCESS on success or variant of hackrf_error

## ◆ hackrf_device_list()

hackrf_device_list_t * hackrf_device_list | ( |  | ) |

Returns
  list of connected devices. The list should be freed with hackrf_device_list_free

## ◆ hackrf_device_list_free()

void hackrf_device_list_free | ( | hackrf_device_list_t * | list | ) |

Parameters

  [in] | list | list to free

## ◆ hackrf_device_list_open()

int hackrf_device_list_open | ( | hackrf_device_list_t * | list,
|  | int | idx,
|  | hackrf_device ** | device
| ) |  |

Parameters

  [in] | list | device list to open device from
  [in] | idx | index of the device to open
  [out] | device | device handle to open

Returns
  HACKRF_SUCCESS on success, HACKRF_ERROR_INVALID_PARAM on invalid parameters or other hackrf_error variant

## ◆ hackrf_open()

int hackrf_open | ( | hackrf_device ** | device | ) |

Parameters

  [out] | device | device handle

Returns
  HACKRF_SUCCESS on success, HACKRF_ERROR_INVALID_PARAM if `device` is NULL, HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other hackrf_error variant

## ◆ hackrf_open_by_serial()

int hackrf_open_by_serial | ( | const char *const | desired_serial_number,
|  | hackrf_device ** | device
| ) |  |

Parameters

  [in] | desired_serial_number | serial number of device to open. If NULL then default to first device found.
  [out] | device | device handle

Returns
  HACKRF_SUCCESS on success, HACKRF_ERROR_INVALID_PARAM if `device` is NULL, HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other hackrf_error variant

## ◆ hackrf_reset()

int hackrf_reset | ( | hackrf_device * | device | ) |

Requires USB API version 0x0102 or above!

Parameters

  device | device to reset

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_set_leds()

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!

Parameters

  device | device to query
  state | LED states as a bitfield

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_set_ui_enable()

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!

Parameters

  device | device to enable/disable UI on
  value | Enable UI. Must be 1 or 0

Returns
  HACKRF_SUCCESS on success or HACKRF_ERROR_LIBUSB on usb error

## ◆ hackrf_set_user_bias_t_opts()

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

Parameters

  device | device to configure
  state | Bias tee states, as a bitfield

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_supported_platform_read()

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!

Parameters

  [in] | device | device to query
  [out] | value | supported platform bitfield

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_usb_api_version_read()

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:

printf("Firmware Version: %s (API:%x.%02x)\n",
version,
(usb_version >> 8) & 0xFF,
usb_version & 0xFF);

Parameters

  [in] | device | device to query
  [out] | version | USB API version

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## ◆ hackrf_usb_board_id_name()

const char * hackrf_usb_board_id_name | ( | enum hackrf_usb_board_id | usb_board_id | ) |

Parameters

  usb_board_id | enum to convert

Returns
  human-readable name of board id

## ◆ hackrf_version_string_read()

int hackrf_version_string_read | ( | hackrf_device * | device,
|  | char * | version,
|  | uint8_t | length
| ) |  |

Parameters

  [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`)

Returns
  HACKRF_SUCCESS on success or hackrf_error variant