Power Amplifier (PA)
RAIL API > Transmit

APIs for interacting with one of the on chip PAs.

Modules

EFR32
Types specific to the EFR32 for dealing with the on chip PAs.

Macros

#define RAIL_TX_POWER_MAX   ((RAIL_TxPower_t)0x7FFF)
 The maximum valid value for a RAIL_TxPower_t.
 
#define RAIL_TX_POWER_MIN   ((RAIL_TxPower_t)0x8000)
 The minimum valid value for a RAIL_TxPower_t.
 
#define RAIL_TX_POWER_VOLTAGE_SCALING_FACTOR   1000
 mV are used for all TX power voltage values TX power voltages take and return voltages multiplied by this factor
 
#define RAIL_TX_POWER_DBM_SCALING_FACTOR   10
 deci-dBm are used for all TX power dBm values All dBm inputs to TX power functions take dBm power times this factor

Typedefs

typedef int16_t RAIL_TxPower_t
 The transmit power in deci-dBm units (e.g.

Functions

RAIL_Status_t RAIL_ConfigTxPower (RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t *config)
 Initialize TxPower Settings.
 
RAIL_Status_t RAIL_GetTxPowerConfig (RAIL_Handle_t railHandle, RAIL_TxPowerConfig_t *config)
 Get the TX power settings currently used in the amplifier.
 
RAIL_Status_t RAIL_SetTxPower (RAIL_Handle_t railHandle, RAIL_TxPowerLevel_t powerLevel)
 Set the TX power in units of raw units (see rail_chip_specific.h for value ranges).
 
RAIL_TxPowerLevel_t RAIL_GetTxPower (RAIL_Handle_t railHandle)
 Returns the current power setting of the PA.
 
RAIL_TxPower_t RAIL_ConvertRawToDbm (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPowerLevel_t powerLevel)
 Converts raw values written to registers to decibel value (in units of deci-dBm).
 
RAIL_TxPowerLevel_t RAIL_ConvertDbmToRaw (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t power)
 Converts the desired decibel value (in units of deci-dBm) to raw integer values used by the TX amplifier registers.

Detailed Description

APIs for interacting with one of the on chip PAs.

These APIs let you configure the on chip PA to get the appropriate output power.

There a few types of functions that are found here 1) Configuration functions: These functions set and get configuration for the PA. In this case, "configuration" refers to a) indicating which PA to use, b) the voltage supplied by your board to the PA, and c) the ramp time over which to ramp the PA up to its full power. 2) Power-setting functions: These functions consume the actual values written to the PA registers, and write them appropriately. These values are referred to as "(raw) power levels". The range of acceptable values for these functions depends on which PA is currently active. The higher the power level set, the higher the dBm power actually output by the chip. However, the mapping between dBm and these power levels can vary greatly between modules/boards. 3) Conversion functions: These functions do the work of converting between the "power levels" discussed previously and the actual dBm values output by the chip. Continue reading for more details on how to handle unit conversion.

The accuracy of the chip output power in dBm will vary from application to to application. For some protocols or channels the protocol itself or legal limitations will require applications to know exactly what power they're transmitting at, in dBm. Other applications will not have these restrictions, and users will simply find some power level(s) that fit their criteria for the trade-off between radio range and power savings, regardless of what dBm power that maps to.

In order to provide a solution that fits all these applications, Silicon Labs has provided a great deal of flexibility in RAIL_ConvertRawToDbm and RAIL_ConvertDbmToRaw, the two functions that do the conversion between the dBm power and the raw power levels. Those levels of customizability are outlined below 1) No customizability needed: for a given dBm value, the result of RAIL_ConvertDbmToRaw provides an appropriate raw power level that, when written to the registers via RAIL_SetPowerLevel, causes the chip to actually output at that dBm power. In this case, no action is needed by the user, the WEAK versions of the conversion functions can be used, and the default include paths in pa_conversions_efr32.h can be used. 2) The mapping of power level to dBm is not good, but the level of precision is sufficient: In pa_conversions_efr32.c the WEAK versions of the conversion functions work by using 8-segment piecewise linear curves to convert between dBm and power levels for PA's with hundreds of power levels and simple mapping tables for use with PA's with only a few levels. If this method is sufficiently precise, but the mapping between power levels and dBm is wrong, Silicon Labs recommends copying pa_curves_efr32.h into a new file, updating the segments to form a better fit (_DCDC_CURVES or _VBAT_CURVES defines), and then adding the RAIL_PA_CURVES define to your build with the path to the new file. 3) A different level of precision is needed and the fit is bad: If the piecewise-linear line segment fit is not appropriate for your solution, the functions in pa_conversions_efr32.c can be totally rewritten, as long as RAIL_ConvertDbmToRaw and RAIL_ConvertRawToDbm have the same signatures. It is completely acceptable to re-write these in a way that makes the pa_curves_efr32.h and pa_curve_types_efr32.h files referenced in pa_conversions_efr32.h unnecessary. Those files are needed solely for the conversion methods that Silicon Labs provides. 4) dBm values are not necessary: If your application does not require dBm values at all, Silicon Labs recommends overwriting RAIL_ConvertDbmToRaw and RAIL_ConvertRawToDbm with smaller functions (i.e. return 0 or whatever was input). These functions are called from within the RAIL library, so they can never be deadstripped, but making them as small as possible is the best way to reduce code size. From there, you can simply call RAIL_SetTxPower, without converting from a dBm value. If you never want the library to coerce the power based on channels, RAIL_ConvertRawToDbm should be overwritten to always return 0 and RAIL_ConvertDbmToRaw should be overwritten to always return 255.

The following is example code on how to initialize your PA

#include "pa_conversions_efr32.h"
// Helper macro to declare all the curve structures used by the Silicon Labs-provided
// conversion functions
RAIL_DECLARE_TX_POWER_VBAT_CURVES(piecewiseSegments, curvesSg, curves24Hp, curves24Lp);
// Put the variables declared above into the appropriate structure
RAIL_TxPowerCurvesConfig_t txPowerCurvesConfig = { curves24Hp, curvesSg, curves24Lp, piecewiseSegments };
// In the Silicon Labs implementation, the user is required to save those curves into
// to be referenced when the conversion functions are called
RAIL_InitTxPowerCurves(&txPowerCurvesConfig);
// Declare the structure used to configure the PA
RAIL_TxPowerConfig_t txPowerConfig = { RAIL_TX_POWER_MODE_2P4_HP, 3300, 10 };
// And then init the PA. Here, it is assumed that 'railHandle' is a valid RAIL_Handle_t
// that has already been initialized.
RAIL_ConfigTxPower(railHandle, &txPowerConfig);
// Pick a dBm power to use: 100 deci-dBm = 10 dBm. See docs on RAIL_TxPower_t
RAIL_TxPower_t power = 100;
// Get the config written by RAIL_ConfigTxPower to confirm what was actually set
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);
// RAIL_ConvertDbmToRaw will be the weak version provided by Silicon Labs
// by default, or the customer version, if overwritten.
RAIL_TxPowerLevel_t powerLevel = RAIL_ConvertDbmToRaw(railHandle,
txPowerConfig.mode,
power);
// Write the result of the conversion to the PA power registers in terms
// of raw power levels
RAIL_SetTxPower(railHandle, powerLevel);
Note
: all the lines following "RAIL_TxPower_t power = 100;" can be replaced with the provided utility function, RAIL_SetTxPowerDbm. However, the full example here was provided for clarity. See the documentation on RAIL_SetTxPowerDbm for more details.

Macro Definition Documentation

◆ RAIL_TX_POWER_MAX

#define RAIL_TX_POWER_MAX   ((RAIL_TxPower_t)0x7FFF)

The maximum valid value for a RAIL_TxPower_t.

Definition at line 652 of file rail_types.h.

◆ RAIL_TX_POWER_MIN

#define RAIL_TX_POWER_MIN   ((RAIL_TxPower_t)0x8000)

The minimum valid value for a RAIL_TxPower_t.

Definition at line 654 of file rail_types.h.

Typedef Documentation

◆ RAIL_TxPower_t

typedef int16_t RAIL_TxPower_t

The transmit power in deci-dBm units (e.g.

4.5dBm -> 45 deci-dBm). These values are used by the conversion functions to convert a RAIL_TxPowerLevel_t to deci-dBm for application consumption. On the EFR32 they can range from RAIL_TX_POWER_MIN to RAIL_TX_POWER_MAX.

Definition at line 650 of file rail_types.h.

Function Documentation

◆ RAIL_ConfigTxPower()

RAIL_Status_t RAIL_ConfigTxPower ( RAIL_Handle_t  railHandle,
const RAIL_TxPowerConfig_t *  config 
)

Initialize TxPower Settings.

Parameters
[in]railHandleA RAIL instance handle.
[in]configInstance which contains desired initial settings for the TX amplifier.
Returns
RAIL_Status_t indicating success or an error.

These settings include the selection between the multiple TX amplifiers, voltage supplied to the TX power amplifier, and ramp times. This must be called before any transmit occurs, or RAIL_SetTxPower is called. While we recommend always calling this function during initialization, it can also be called anytime if these settings need to change to adapt to a different application/protocol. This API will also reset TX Power to its minimum value, so RAIL_SetTxPower must be called after calling this.

At times, certain combinations of configurations cannot be achieved. This API attempts to get as close as possible to the requested settings. The following "RAIL_Get..." API can be used to determine what values were set.

◆ RAIL_ConvertDbmToRaw()

RAIL_TxPowerLevel_t RAIL_ConvertDbmToRaw ( RAIL_Handle_t  railHandle,
RAIL_TxPowerMode_t  mode,
RAIL_TxPower_t  power 
)

Converts the desired decibel value (in units of deci-dBm) to raw integer values used by the TX amplifier registers.

Parameters
[in]railHandleA RAIL instance handle.
[in]modePA mode for which to do the conversion.
[in]powerDesired dBm values in units of deci-dBm.
Returns
deci-dBm value converted to a raw integer value that can be used directly with RAIL_SetTxPower.

A weak version of this function is provided by Silicon Labs that is tuned to provide accurate values for our boards. If the customer intends to use a custom board, the relationship between what is written to the TX amplifier and the actual output power should be characterized and implemented in an overriding version of RAIL_ConvertDbmToRaw. For minimum code size and best speed use only raw values with the TxPower API and override this function with a smaller function. In the weak version provided with the RAIL library, railHandle is only used to indicate to the user from where the function was called, so it is OK to use either a real protocol handle, or one of the chip specific ones, such as RAIL_EFR32_HANDLE.

Although the definitions of this function may change, the signature must be as declared here.

Note
This function is called from within the RAIL library for comparison between channel limitations and current power. It will throw an assert if you haven't called RAIL_InitTxPowerCurves which initializes the mappings between raw power levels and actual dBm powers. To avoid this assert, ensure that the maxPower of all channel config entries is RAIL_TX_POWER_MAX or above, or override this function to always return 255.

◆ RAIL_ConvertRawToDbm()

RAIL_TxPower_t RAIL_ConvertRawToDbm ( RAIL_Handle_t  railHandle,
RAIL_TxPowerMode_t  mode,
RAIL_TxPowerLevel_t  powerLevel 
)

Converts raw values written to registers to decibel value (in units of deci-dBm).

Parameters
[in]railHandleA RAIL instance handle.
[in]modePA mode for which to do the conversion.
[in]powerLevelRaw amplifier register value to be converted to deci-dBm.
Returns
raw amplifier values converted to units of deci-dBm.

A weak version of this function is provided by Silicon Labs that is tuned to provide accurate values for our boards. If the customer intends to use a custom board, the relationship between what is written to the Tx amplifier and the actual output power should be re-characterized and implemented in an overriding version of RAIL_ConvertRawToDbm. For minimum code size and best speed use only raw values with the TxPower API and override this function with a smaller function. In the weak version provided with the RAIL library, railHandle is only used to indicate to the user from where the function was called, so it is OK to use either a real protocol handle, or one of the chip specific ones, such as RAIL_EFR32_HANDLE.

Although the definitions of this function may change, the signature must be as declared here.

◆ RAIL_GetTxPower()

RAIL_TxPowerLevel_t RAIL_GetTxPower ( RAIL_Handle_t  railHandle)

Returns the current power setting of the PA.

Parameters
[in]railHandleA RAIL instance handle.
Returns
The chip specific RAIL_TxPowerLevel_t value of the current transmit power.

This API returns the raw value that was actually set by RAIL_SetTxPower. Silicon Labs provides a weak version of RAIL_ConvertRawToDbm that works with our boards to convert these raw values into actual output dBm values. However, if a customer is using a custom board, we recommend that he/she re- characterizes the relationship between raw and decibel values, and overrides the provided function with one more that more accurately reflects the actual relationship.

Calling this function before configuring the PA (i.e. before a successful call to RAIL_ConfigTxPower) will cause an error to be returned (RAIL_TX_POWER_LEVEL_INVALID).

◆ RAIL_GetTxPowerConfig()

RAIL_Status_t RAIL_GetTxPowerConfig ( RAIL_Handle_t  railHandle,
RAIL_TxPowerConfig_t *  config 
)

Get the TX power settings currently used in the amplifier.

Parameters
[in]railHandleA RAIL instance handle.
[out]configPointer to memory allocated to hold current TxPower configuration structure.
Returns
RAIL_TxPowerConfig_t RAIL status variable indicating whether or not the get was successful.

Note, this API does not return the current TX power - that is separately managed by the RAIL_GetTxPower/RAIL_SetTxPower API's. This API should be used to know exactly which values were set as a result of RAIL_ConfigTxPower.

◆ RAIL_SetTxPower()

RAIL_Status_t RAIL_SetTxPower ( RAIL_Handle_t  railHandle,
RAIL_TxPowerLevel_t  powerLevel 
)

Set the TX power in units of raw units (see rail_chip_specific.h for value ranges).

Parameters
[in]railHandleA RAIL instance handle.
[in]powerLevelPower in chip specific RAIL_TxPowerLevel_t units.
Returns
RAIL_Status_t indicating success or an error.

In order to convert between decibels and the integer values that the registers take, call RAIL_ConvertDbmToRaw. Silicon Labs provides a weak version of this function which works well with our boards. However a customer using his/her own custom board will want to characterize chip operation on that board and override the function to do the conversion appropriately from the desired dB values to raw integer values.

Depending on the configuration used in RAIL_ConfigTxPower, not all power levels are achievable. This API will get as close as possible to the desired power without exceeding it, and calling RAIL_GetTxPower is the only way to know the exact value written.

Calling this function before configuring the PA (i.e. before a successful call to RAIL_ConfigTxPower) will cause an error to be returned.