libbladeRF: Gain

| libbladeRF 2.2.1-git Nuand bladeRF library

Data Structures | Typedefs | Enumerations | Macros | Functions
Gain
Channel control

## Description

These functions provide control over the device's RX and TX gain stages.

These functions are thread-safe.

## Data Structures
struct | bladerf_gain_modes

## Typedefs
typedef int | bladerf_gain

## Enumerations
enum | bladerf_gain_mode { BLADERF_GAIN_DEFAULT, BLADERF_GAIN_MGC, BLADERF_GAIN_FASTATTACK_AGC, BLADERF_GAIN_SLOWATTACK_AGC, BLADERF_GAIN_HYBRID_AGC }

## Macros
#define | BLADERF_GAIN_AUTOMATIC BLADERF_GAIN_DEFAULT
#define | BLADERF_GAIN_MANUAL BLADERF_GAIN_MGC

## Functions
API_EXPORT int CALL_CONV | bladerf_set_gain (struct bladerf *dev, bladerf_channel ch, bladerf_gain gain)
API_EXPORT int CALL_CONV | bladerf_get_gain (struct bladerf *dev, bladerf_channel ch, bladerf_gain *gain)
API_EXPORT int CALL_CONV | bladerf_set_gain_mode (struct bladerf *dev, bladerf_channel ch, bladerf_gain_mode mode)
API_EXPORT int CALL_CONV | bladerf_get_gain_mode (struct bladerf *dev, bladerf_channel ch, bladerf_gain_mode *mode)
API_EXPORT int CALL_CONV | bladerf_get_gain_modes (struct bladerf *dev, bladerf_channel ch, const struct bladerf_gain_modes **modes)
API_EXPORT int CALL_CONV | bladerf_get_gain_range (struct bladerf *dev, bladerf_channel ch, const struct bladerf_range **range)
API_EXPORT int CALL_CONV | bladerf_set_gain_stage (struct bladerf *dev, bladerf_channel ch, const char *stage, bladerf_gain gain)
API_EXPORT int CALL_CONV | bladerf_get_gain_stage (struct bladerf *dev, bladerf_channel ch, const char *stage, bladerf_gain *gain)
API_EXPORT int CALL_CONV | bladerf_get_gain_stage_range (struct bladerf *dev, bladerf_channel ch, const char *stage, const struct bladerf_range **range)
API_EXPORT int CALL_CONV | bladerf_get_gain_stages (struct bladerf *dev, bladerf_channel ch, const char **stages, size_t count)

## Typedef Documentation

## ◆ bladerf_gain

typedef int bladerf_gain

Gain value, in decibels (dB)

May be positive or negative.

Definition at line 723 of file libbladeRF.h.

## Enumeration Type Documentation

## ◆ bladerf_gain_mode

enum bladerf_gain_mode

Gain control modes

In general, the default mode is automatic gain control. This will continuously adjust the gain to maximize dynamic range and minimize clipping.

Note
  Implementers are encouraged to simply present a boolean choice between "AGC On" (BLADERF_GAIN_DEFAULT) and "AGC Off" (BLADERF_GAIN_MGC). The remaining choices are for advanced use cases.

Enumerator
BLADERF_GAIN_DEFAULT | Device-specific default (automatic, when available) On the bladeRF x40 and x115 with FPGA versions >= v0.7.0, this is automatic gain control. On the bladeRF 2.0 Micro, this is BLADERF_GAIN_SLOWATTACK_AGC with reasonable default settings.
BLADERF_GAIN_MGC | Manual gain control Available on all bladeRF models.
BLADERF_GAIN_FASTATTACK_AGC | Automatic gain control, fast attack (advanced) Only available on the bladeRF 2.0 Micro. This is an advanced option, and typically requires additional configuration for ideal performance.
BLADERF_GAIN_SLOWATTACK_AGC | Automatic gain control, slow attack (advanced) Only available on the bladeRF 2.0 Micro. This is an advanced option, and typically requires additional configuration for ideal performance.
BLADERF_GAIN_HYBRID_AGC | Automatic gain control, hybrid attack (advanced) Only available on the bladeRF 2.0 Micro. This is an advanced option, and typically requires additional configuration for ideal performance.

Definition at line 735 of file libbladeRF.h.

## Macro Definition Documentation

## ◆ BLADERF_GAIN_AUTOMATIC

#define BLADERF_GAIN_AUTOMATIC BLADERF_GAIN_DEFAULT

Default AGC mode (for backwards compatibility with libbladeRF 1.x)

Definition at line 775 of file libbladeRF.h.

## ◆ BLADERF_GAIN_MANUAL

#define BLADERF_GAIN_MANUAL BLADERF_GAIN_MGC

Manual gain control (for backwards compatibility with libbladeRF 1.x)

Definition at line 777 of file libbladeRF.h.

## Function Documentation

## ◆ bladerf_get_gain()

API_EXPORT int CALL_CONV bladerf_get_gain | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | bladerf_gain * | gain
| ) |  |

Get overall system gain

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [out] | gain | Gain, in dB

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_get_gain_mode()

API_EXPORT int CALL_CONV bladerf_get_gain_mode | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | bladerf_gain_mode * | mode
| ) |  |

Get gain control mode

Gets the current mode for hardware AGC. If the channel or board does not meaningfully have a gain mode (e.g. transmit channels), mode will be set to BLADERF_GAIN_DEFAULT and `0` will be returned.

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [out] | mode | Gain mode

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_get_gain_modes()

API_EXPORT int CALL_CONV bladerf_get_gain_modes | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | const struct bladerf_gain_modes ** | modes
| ) |  |

Get available gain control modes

Populates `modes` with a pointer to an array of structs containing the supported gain modes.

This function may be called with `NULL` for `modes` to determine the number of gain modes supported.

See also
  bladerf_gain_mode for implementation guidance

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [out] | modes | Supported gain modes

Returns
  Number of gain modes on success, value from Error codes list on failure

## ◆ bladerf_get_gain_range()

API_EXPORT int CALL_CONV bladerf_get_gain_range | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | const struct bladerf_range ** | range
| ) |  |

Get range of overall system gain

Note
  This may vary depending on the configured frequency, so it should be checked after setting the desired frequency.

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [out] | range | Gain range

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_get_gain_stage()

API_EXPORT int CALL_CONV bladerf_get_gain_stage | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | const char * | stage,
|  | bladerf_gain * | gain
| ) |  |

Set the gain for a specific gain stage

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [in] | stage | Gain stage name
  [out] | gain | Gain

Note that, in some cases, gain may be negative (e.g. transmit channels).

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_get_gain_stage_range()

API_EXPORT int CALL_CONV bladerf_get_gain_stage_range | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | const char * | stage,
|  | const struct bladerf_range ** | range
| ) |  |

Get gain range of a specific gain stage

Note
  This may vary depending on the configured frequency, so it should be checked after setting the desired frequency.

This function may be called with `NULL` for `range` to test if a given gain range exists.

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [in] | stage | Gain stage name
  [out] | range | Gain range

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_get_gain_stages()

API_EXPORT int CALL_CONV bladerf_get_gain_stages | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | const char ** | stages,
|  | size_t | count
| ) |  |

Get a list of available gain stages

This function may be called with `NULL` for `stages`, or 0 for `count`, to determine the number of gain stages.

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [out] | stages | Gain stage names
  [out] | count | Number to populate

Returns
  Number of gain stages on success, value from Error codes list on failure

## ◆ bladerf_set_gain()

API_EXPORT int CALL_CONV bladerf_set_gain | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | bladerf_gain | gain
| ) |  |

Set overall system gain

This sets an overall system gain, optimally proportioning the gain between multiple gain stages if applicable.

See also
  Use bladerf_get_gain_range() to determine the range of system gain.

On receive channels, 60 dB is the maximum gain level.

On transmit channels, 60 dB is defined as approximately 0 dBm. Note that this is not a calibrated value, and the actual output power will vary based on a multitude of factors.

Todo:
  The gain ranges are not shifted to account for external accessories, such as amplifiers and LNAs.

Note
  Values outside the valid gain range will be clamped.

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [in] | gain | Desired gain, in dB

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_set_gain_mode()

API_EXPORT int CALL_CONV bladerf_set_gain_mode | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | bladerf_gain_mode | mode
| ) |  |

Set gain control mode

Sets the mode for hardware AGC. Not all channels or boards will support all possible values (e.g. transmit channels); invalid combinations will return BLADERF_ERR_UNSUPPORTED.

The special value of BLADERF_GAIN_DEFAULT will return hardware AGC to its default value at initialization.

See also
  bladerf_gain_mode for implementation guidance

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [in] | mode | Desired gain mode

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_set_gain_stage()

API_EXPORT int CALL_CONV bladerf_set_gain_stage | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | const char * | stage,
|  | bladerf_gain | gain
| ) |  |

Set the gain for a specific gain stage

Note
  Values outside the valid gain range will be clipped.

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [in] | stage | Gain stage name
  [in] | gain | Desired gain

Returns
  0 on success, value from Error codes list on failure