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.

#define	HACKRF_PLATFORM_JAWBREAKER (1 << 0)
	JAWBREAKER platform bit in result of hackrf_supported_platform_read.

#define	HACKRF_PLATFORM_HACKRF1_OG (1 << 1)
	HACKRF ONE (pre r9) platform bit in result of hackrf_supported_platform_read.

#define	HACKRF_PLATFORM_RAD1O (1 << 2)
	RAD1O platform bit in result of hackrf_supported_platform_read.

#define	HACKRF_PLATFORM_HACKRF1_R9 (1 << 3)
	HACKRF ONE (r9 or later) platform bit in result of hackrf_supported_platform_read.

#define	HACKRF_PLATFORM_PRALINE (1 << 4)
	HACKRF Praline platform bit in result of hackrf_supported_platform_read.

#define	BOARD_ID_HACKRF_ONE (BOARD_ID_HACKRF1_OG)
	These deprecated board ID names are provided for API compatibility.

#define	BOARD_ID_INVALID (BOARD_ID_UNDETECTED)
	These deprecated board ID names are provided for API compatibility.

Typedefs
typedef struct hackrf_device	hackrf_device
	Opaque struct for hackrf device info.

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_PRALINE = 5 , 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_PRALINE_R0_1 = 6 , BOARD_REV_PRALINE_R0_2 = 7 , BOARD_REV_PRALINE_R0_3 = 8 , BOARD_REV_PRALINE_R1_0 = 9 , BOARD_REV_PRALINE_R1_1 = 10 , BOARD_REV_PRALINE_R1_2 = 11 , 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_GSG_PRALINE_R0_1 = 0x86 , BOARD_REV_GSG_PRALINE_R0_2 = 0x87 , BOARD_REV_GSG_PRALINE_R0_3 = 0x88 , BOARD_REV_GSG_PRALINE_R1_0 = 0x89 , BOARD_REV_GSG_PRALINE_R1_1 = 0x8a , BOARD_REV_GSG_PRALINE_R1_2 = 0x8b , 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.

int	hackrf_device_list_open (hackrf_device_list_t list, int idx, hackrf_device *device)
	Open a hackrf_device from a device list.

void	hackrf_device_list_free (hackrf_device_list_t *list)
	Free a previously allocated hackrf_device_list list.

int	hackrf_open (hackrf_device **device)
	Open first available HackRF device.

int	hackrf_open_by_serial (const char const desired_serial_number, hackrf_device *device)
	Open HackRF device by serial number.

int	hackrf_close (hackrf_device *device)
	Close a previously opened device.

int	hackrf_board_id_read (hackrf_device device, uint8_t value)
	Read hackrf_board_id from a device.

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.

int	hackrf_board_partid_serialno_read (hackrf_device device, read_partid_serialno_t read_partid_serialno)
	Read board part ID and serial number.

const char *	hackrf_board_id_name (enum hackrf_board_id board_id)
	Convert hackrf_board_id into human-readable string.

uint32_t	hackrf_board_id_platform (enum hackrf_board_id board_id)
	Lookup platform ID (HACKRF_PLATFORM_xxx) from board id (hackrf_board_id)

const char *	hackrf_usb_board_id_name (enum hackrf_usb_board_id usb_board_id)
	Convert hackrf_usb_board_id into human-readable string.

int	hackrf_reset (hackrf_device *device)
	Reset HackRF device.

int	hackrf_set_ui_enable (hackrf_device *device, const uint8_t value)
	Enable / disable UI display (RAD1O, PortaPack, etc.)

int	hackrf_board_rev_read (hackrf_device device, uint8_t value)
	Read board revision of device.

const char *	hackrf_board_rev_name (enum hackrf_board_rev board_rev)
	Convert board revision name.

int	hackrf_supported_platform_read (hackrf_device device, uint32_t value)
	Read supported platform of device.

int	hackrf_set_leds (hackrf_device *device, const uint8_t state)
	Turn on or off (override) the LEDs of the HackRF device.

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.

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

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 firmware 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_PRALINE

#define HACKRF_PLATFORM_PRALINE (1 << 4)

◆ 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_PRALINE	Praline.
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_PRALINE_R0_1	praline board revision 0.1, generic
BOARD_REV_PRALINE_R0_2	praline board revision 0.2, generic
BOARD_REV_PRALINE_R0_3	praline board revision 0.1, generic
BOARD_REV_PRALINE_R1_0	praline board revision 1.0, generic
BOARD_REV_PRALINE_R1_1	praline board revision 1.1, generic
BOARD_REV_PRALINE_R1_2	praline board revision 1.2, 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_GSG_PRALINE_R0_1	praline board revision 0.1, made by GSG
BOARD_REV_GSG_PRALINE_R0_2	praline board revision 0.2, made by GSG
BOARD_REV_GSG_PRALINE_R0_3	praline board revision 0.1, made by GSG
BOARD_REV_GSG_PRALINE_R1_0	praline board revision 1.0, made by GSG
BOARD_REV_GSG_PRALINE_R1_1	praline board revision 1.1, made by GSG
BOARD_REV_GSG_PRALINE_R1_2	praline board revision 1.2, 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 )

extern

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 )

extern

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
	)

extern

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
	)

extern

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 )

extern

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
	)

extern

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 )

extern

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

extern

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 )

extern

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
	)

extern

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 )

extern

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
	)

extern

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 )

extern

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
	)

extern

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
	)

extern

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
	)

extern

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
	)

extern

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
	)

extern

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 )

extern

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
	)

extern

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Opening devices

Open first device

Open by serial

Open by listing

Closing devices

Querying device information

Board ID

Version string

USB API version

Part ID and serial number

Board revision

Supported platform

Macro Definition Documentation

◆ BOARD_ID_HACKRF_ONE

◆ BOARD_ID_INVALID

◆ HACKRF_BOARD_REV_GSG

◆ HACKRF_PLATFORM_HACKRF1_OG

◆ HACKRF_PLATFORM_HACKRF1_R9

◆ HACKRF_PLATFORM_JAWBREAKER

◆ HACKRF_PLATFORM_PRALINE

◆ HACKRF_PLATFORM_RAD1O

Typedef Documentation

◆ hackrf_device

Enumeration Type Documentation

◆ hackrf_board_id

◆ hackrf_board_rev

◆ hackrf_usb_board_id

Function Documentation

◆ hackrf_board_id_name()

◆ hackrf_board_id_platform()

◆ hackrf_board_id_read()

◆ hackrf_board_partid_serialno_read()

◆ hackrf_board_rev_name()

◆ hackrf_board_rev_read()

◆ hackrf_close()

◆ hackrf_device_list()

◆ hackrf_device_list_free()

◆ hackrf_device_list_open()

◆ hackrf_open()

◆ hackrf_open_by_serial()

◆ hackrf_reset()

◆ hackrf_set_leds()

◆ hackrf_set_ui_enable()

◆ hackrf_set_user_bias_t_opts()

◆ hackrf_supported_platform_read()

◆ hackrf_usb_api_version_read()

◆ hackrf_usb_board_id_name()

◆ hackrf_version_string_read()