Opera Cake add-on board functions

Various functions related to the Opera Cake add-on boards. More...

## Data Structures

struct | hackrf_operacake_dwell_time
| Opera Cake port setting in OPERACAKE_MODE_TIME operation. More...
struct | hackrf_operacake_freq_range
| Opera Cake port setting in OPERACAKE_MODE_FREQUENCY operation. More...

## Macros

#define | HACKRF_OPERACAKE_ADDRESS_INVALID 0xFF
| Invalid Opera Cake add-on board address, placeholder in hackrf_get_operacake_boards. More...
#define | HACKRF_OPERACAKE_MAX_BOARDS 8
| Maximum number of connected Opera Cake add-on boards. More...
#define | HACKRF_OPERACAKE_MAX_DWELL_TIMES 16
| Maximum number of specifiable dwell times for Opera Cake add-on boards. More...
#define | HACKRF_OPERACAKE_MAX_FREQ_RANGES 8
| Maximum number of specifiable frequency ranges for Opera Cake add-on boards. More...

## Enumerations

enum | operacake_ports { OPERACAKE_PA1 = 0 , OPERACAKE_PA2 = 1 , OPERACAKE_PA3 = 2 , OPERACAKE_PA4 = 3 , OPERACAKE_PB1 = 4 , OPERACAKE_PB2 = 5 , OPERACAKE_PB3 = 6 , OPERACAKE_PB4 = 7 }
| Opera Cake secondary ports (A1-A4, B1-B4) More...
enum | operacake_switching_mode { OPERACAKE_MODE_MANUAL , OPERACAKE_MODE_FREQUENCY , OPERACAKE_MODE_TIME }
| Opera Cake port switching mode. More...

## Functions

int | hackrf_get_operacake_boards (hackrf_device *device, uint8_t *boards)
| Query connected Opera Cake boards. More...
int | hackrf_set_operacake_mode (hackrf_device *device, uint8_t address, enum operacake_switching_mode mode)
| Setup Opera Cake operation mode. More...
int | hackrf_get_operacake_mode (hackrf_device *device, uint8_t address, enum operacake_switching_mode *mode)
| Query Opera Cake mode. More...
int | hackrf_set_operacake_ports (hackrf_device *device, uint8_t address, uint8_t port_a, uint8_t port_b)
| Setup Opera Cake ports in OPERACAKE_MODE_MANUAL mode operation. More...
int | hackrf_set_operacake_dwell_times (hackrf_device *device, hackrf_operacake_dwell_time *dwell_times, uint8_t count)
| Setup Opera Cake dwell times in OPERACAKE_MODE_TIME mode operation. More...
int | hackrf_set_operacake_freq_ranges (hackrf_device *device, hackrf_operacake_freq_range *freq_ranges, uint8_t count)
| Setup Opera Cake frequency ranges in OPERACAKE_MODE_FREQUENCY mode operation. More...
int | hackrf_set_operacake_ranges (hackrf_device *device, uint8_t *ranges, uint8_t num_ranges)
| Setup Opera Cake frequency ranges in OPERACAKE_MODE_FREQUENCY mode operation. More...
int | hackrf_operacake_gpio_test (hackrf_device *device, uint8_t address, uint16_t *test_result)
| Perform GPIO test on an Opera Cake addon board. More...

## Detailed Description

These boards are versatile RF switching boards capable of switching two primary ports (A0 and B0) to any of 8 (A1-A4 and B1-B4) secondary ports (with the only rule that A0 and B0 can not be connected to the same side/bank of secondary ports at the same time).

There are 3 operating modes:

- manual setup
- frequency-based setup
- time-based setup

### Manual setup

This mode allows A0 and B0 to be connected to any of the secondary ports. This mode is configured with hackrf_set_operacake_ports.

### Frequency-based setup

In this mode the Opera Cake board automatically switches A0 to a port depending on the tuning frequency. Up to HACKRF_OPERACAKE_MAX_FREQ_RANGES frequency ranges can be setup using hackrf_set_operacake_freq_ranges, in a priority order. Port B0 mirrors A0 on the opposite side (but both B and A side ports can be specified for connections to A0)

### Time-based setup

In this mode the Opera Cake board automatically switches A0 to a port for a set amount of time (specified in samples). Up to HACKRF_OPERACAKE_MAX_DWELL_TIMES times can be setup via hackrf_set_operacake_dwell_times. Port B0 mirrors A0 on the opposite side.

## Opera Cake setup

Opera Cake boards can be listed with hackrf_get_operacake_boards, but if only one board is connected, than using address 0 defaults to it.

Opera Cake mode can be setup via hackrf_set_operacake_mode, then the corresponding configuration function can be called.

## Multiple boards

There can be up to HACKRF_OPERACAKE_MAX_BOARDS boards connected to a single HackRF One. They can be assigned individual addresses via onboard jumpers, see the documentation page for details. Note: the operating modes of the boards can be set individually via hackrf_set_operacake_mode, but in frequency or time mode, every board configured to that mode will use the same switching plan!

## Macro Definition Documentation

## HACKRF_OPERACAKE_ADDRESS_INVALID

#define HACKRF_OPERACAKE_ADDRESS_INVALID 0xFF

## HACKRF_OPERACAKE_MAX_BOARDS

#define HACKRF_OPERACAKE_MAX_BOARDS 8

## HACKRF_OPERACAKE_MAX_DWELL_TIMES

#define HACKRF_OPERACAKE_MAX_DWELL_TIMES 16

## HACKRF_OPERACAKE_MAX_FREQ_RANGES

#define HACKRF_OPERACAKE_MAX_FREQ_RANGES 8

## Enumeration Type Documentation

## operacake_ports

enum operacake_ports

Enumerator
OPERACAKE_PA1 |
OPERACAKE_PA2 |
OPERACAKE_PA3 |
OPERACAKE_PA4 |
OPERACAKE_PB1 |
OPERACAKE_PB2 |
OPERACAKE_PB3 |
OPERACAKE_PB4 |

## operacake_switching_mode

enum operacake_switching_mode

Set via hackrf_set_operacake_mode and quaried via hackrf_get_operacake_mode

Enumerator
OPERACAKE_MODE_MANUAL | Port connections are set manually using hackrf_set_operacake_ports. Both ports can be specified, but not on the same side.
OPERACAKE_MODE_FREQUENCY | Port connections are switched automatically when the frequency is changed. Frequency ranges can be set using hackrf_set_operacake_freq_ranges. In this mode, B0 mirrors A0
OPERACAKE_MODE_TIME | Port connections are switched automatically over time. dwell times can be set with hackrf_set_operacake_dwell_times. In this mode, B0 mirrors A0

## Function Documentation

## hackrf_get_operacake_boards()

int hackrf_get_operacake_boards | ( | hackrf_device * | device,
|  | uint8_t * | boards
| ) |  |

Returns a HACKRF_OPERACAKE_MAX_BOARDS size array of addresses, with HACKRF_OPERACAKE_ADDRESS_INVALID as a placeholder

Requires USB API version 0x0105 or above!

Parameters

  [in] | device | device to query
  [out] | boards | list of boards

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_get_operacake_mode()

int hackrf_get_operacake_mode | ( | hackrf_device * | device,
|  | uint8_t | address,
|  | enum operacake_switching_mode * | mode
| ) |  |

Requires USB API version 0x0105 or above!

Parameters

  [in] | device | device to query from
  [in] | address | address of add-on board to query
  [out] | mode | operation mode of the selected add-on board

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_operacake_gpio_test()

int hackrf_operacake_gpio_test | ( | hackrf_device * | device,
|  | uint8_t | address,
|  | uint16_t * | test_result
| ) |  |

Value 0xFFFF means "GPIO mode disabled", and hackrf_operacake advises to remove additional add-on boards and retry. Value 0 means all tests passed. In any other values, a 1 bit signals an error. Bits are grouped in groups of 3. Encoding: 0 - u1ctrl - u3ctrl0 - u3ctrl1 - u2ctrl0 - u2ctrl1

Requires USB API version 0x0103 or above!

Parameters

  [in] | device | device to perform test on
  [in] | address | address of Opera Cake board to test
  [out] | test_result | result of tests

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_set_operacake_dwell_times()

int hackrf_set_operacake_dwell_times | ( | hackrf_device * | device,
|  | hackrf_operacake_dwell_time * | dwell_times,
|  | uint8_t | count
| ) |  |

Should be called after hackrf_set_operacake_mode

Note: this configuration applies to all Opera Cake boards in OPERACAKE_MODE_TIME mode

Requires USB API version 0x0105 or above!

Parameters

  device | device to configure
  dwell_times | list of dwell times to setup
  count | number of dwell times to setup. Must be at most HACKRF_OPERACAKE_MAX_DWELL_TIMES.

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_set_operacake_freq_ranges()

int hackrf_set_operacake_freq_ranges | ( | hackrf_device * | device,
|  | hackrf_operacake_freq_range * | freq_ranges,
|  | uint8_t | count
| ) |  |

Should be called after hackrf_set_operacake_mode

Note: this configuration applies to all Opera Cake boards in OPERACAKE_MODE_FREQUENCY mode

Requires USB API version 0x0103 or above!

Parameters

  device | device to configure
  freq_ranges | list of frequency ranges to setup
  count | number of ranges to setup. Must be at most HACKRF_OPERACAKE_MAX_FREQ_RANGES.

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_set_operacake_mode()

int hackrf_set_operacake_mode | ( | hackrf_device * | device,
|  | uint8_t | address,
|  | enum operacake_switching_mode | mode
| ) |  |

Requires USB API version 0x0105 or above!

Parameters

  device | device to configure
  address | address of Opera Cake add-on board to configure
  mode | mode to use

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_set_operacake_ports()

int hackrf_set_operacake_ports | ( | hackrf_device * | device,
|  | uint8_t | address,
|  | uint8_t | port_a,
|  | uint8_t | port_b
| ) |  |

Should be called after hackrf_set_operacake_mode. A0 and B0 must be connected to opposite sides (A->A and B->B or A->B and B->A but not A->A and B->A or A->B and B->B)

Requires USB API version 0x0102 or above!

Parameters

  device | device to configure
  address | address of add-on board to configure
  port_a | port for A0. Must be one of operacake_ports
  port_b | port for B0. Must be one of operacake_ports

Returns
  HACKRF_SUCCESS on success or hackrf_error variant

## hackrf_set_operacake_ranges()

int hackrf_set_operacake_ranges | ( | hackrf_device * | device,
|  | uint8_t * | ranges,
|  | uint8_t | num_ranges
| ) |  |

Old function to set ranges with. Use hackrf_set_operacake_freq_ranges instead!

Note: this configuration applies to all Opera Cake boards in OPERACAKE_MODE_FREQUENCY mode

Requires USB API version 0x0103 or above!

Parameters

  device | device to configure
  ranges | ranges to setup. Should point to a valid hackrf_operacake_freq_range array.
  num_ranges | length of ranges to setup, must be number of ranges * 5. Must be at most 8*5=40. (internally called len_ranges, possible typo)

Returns
  HACKRF_SUCCESS on success or hackrf_error variant