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

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

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

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

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

◆ 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]devicedevice to query
[out]valuehackrf_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]devicedevice to query
[out]read_partid_serialnoresult 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_revboard 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]devicedevice to read board revision from
[out]valuerevision 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]devicedevice 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]listlist to free

◆ hackrf_device_list_open()

int hackrf_device_list_open ( hackrf_device_list_t *  list,
int  idx,
hackrf_device **  device 
)
Parameters
[in]listdevice list to open device from
[in]idxindex of the device to open
[out]devicedevice 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]devicedevice 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_numberserial number of device to open. If NULL then default to first device found.
[out]devicedevice 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
devicedevice 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
devicedevice to query
stateLED 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
devicedevice to enable/disable UI on
valueEnable 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
devicedevice to configure
stateBias 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]devicedevice to query
[out]valuesupported 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]devicedevice to query
[out]versionUSB 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_idenum 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]devicedevice to query
[out]versionversion string
[in]lengthlength of allocated string without null byte (so set it to length(arr)-1)
Returns
HACKRF_SUCCESS on success or hackrf_error variant