Power Amplifier (PA)#

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.

These are the function types: 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 output by the radio. However, the mapping between dBm and these power levels can vary greatly between modules/boards. 3) Conversion functions: These functions convert between the "power levels" discussed previously and the dBm values output by the radio. Continue reading for more information about unit conversion.

The accuracy of the radio output power is application-specific. For some protocols or channels, the protocol itself or legal limitations require applications to know exactly what power they're transmitting at, in dBm. Other applications do not have these restrictions, and users determine 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.

RAIL_ConvertRawToDbm and RAIL_ConvertDbmToRaw, which convert between the dBm power and the raw power levels, provide a solution that fits all these applications. The levels of customization are outlined below: 1) No customization 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 radio to 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 ideal, 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 incorrect, copy pa_curves_efr32.h into a new file, updating the segments to form a better fit (_DCDC_CURVES or _VBAT_CURVES defines) and then add 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 provided conversion methods. 4) dBm values are not necessary: If the application does not require dBm values at all, overwrite 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, call RAIL_SetTxPower, without converting from a dBm value. To stop the library from coercing the power based on channels, overwrite RAIL_ConvertRawToDbm to always return 0 and overwrite RAIL_ConvertDbmToRaw to always return 255.

The following is example code that shows how to initialize your PA

#include "pa_conversions_efr32.h"

// A macro RAIL_TX_POWER_CURVES_CONFIG is used as the curve
// structures used by the provided conversion functions.
RAIL_TxPowerCurvesConfigAlt_t tx_power_curves_config = RAIL_TX_POWER_CURVES_CONFIG;
// Saves those curves
// to be referenced when the conversion functions are called.
RAIL_InitTxPowerCurves(rail_handle, &tx_power_curves_config);

// Declares the structure used to configure the PA.
RAIL_TxPowerConfig_t txPowerConfig = {
  .mode     = RAIL_TX_POWER_MODE_2P4_HP,
  .voltage  = 3300,
  .rampTime = 10,
};

// Initializes the PA. Here, it is assumed that 'railHandle' is a valid RAIL_Handle_t
// that has already been initialized.
RAIL_ConfigTxPower(railHandle, &txPowerConfig);

// Picks a dBm power to use: 100 deci-dBm = 10 dBm. See docs on RAIL_TxPower_t.
RAIL_TxPower_t power = 100;

// Gets the config written by RAIL_ConfigTxPower to confirm what was actually set.
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);

// RAIL_ConvertDbmToRaw is the default weak version,
// or the customer version, if overwritten.
RAIL_TxPowerLevel_t powerLevel = RAIL_ConvertDbmToRaw(railHandle,
                                                      txPowerConfig.mode,
                                                      power);

// Writes the result of the conversion to the PA power registers in terms
// of raw power levels.
RAIL_SetTxPower(railHandle, powerLevel);

Note

  • All 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.

Modules#

RAIL_TxPowerConfig_t

RAIL_PaAutoModeConfigEntry_t

EFR32XG2X

PA Curve Conversions

Enumerations#

enum
RAIL_TX_POWER_MODE_2P4GIG_HP = 0U
RAIL_TX_POWER_MODE_2P4_HP = RAIL_TX_POWER_MODE_2P4GIG_HP
RAIL_TX_POWER_MODE_2P4GIG_MP = 1U
RAIL_TX_POWER_MODE_2P4_MP = RAIL_TX_POWER_MODE_2P4GIG_MP
RAIL_TX_POWER_MODE_2P4GIG_LP = 2U
RAIL_TX_POWER_MODE_2P4_LP = RAIL_TX_POWER_MODE_2P4GIG_LP
RAIL_TX_POWER_MODE_2P4GIG_LLP = 3U
RAIL_TX_POWER_MODE_2P4GIG_HIGHEST = 4U
RAIL_TX_POWER_MODE_2P4_HIGHEST = RAIL_TX_POWER_MODE_2P4GIG_HIGHEST
RAIL_TX_POWER_MODE_SUBGIG_POWERSETTING_TABLE = 5U
RAIL_TX_POWER_MODE_SUBGIG_HP = 6U
RAIL_TX_POWER_MODE_SUBGIG = RAIL_TX_POWER_MODE_SUBGIG_HP
RAIL_TX_POWER_MODE_SUBGIG_MP = 7U
RAIL_TX_POWER_MODE_SUBGIG_LP = 8U
RAIL_TX_POWER_MODE_SUBGIG_LLP = 9U
RAIL_TX_POWER_MODE_SUBGIG_HIGHEST = 10U
RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE = 11U
RAIL_TX_POWER_MODE_OFDM_PA = RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE
RAIL_TX_POWER_MODE_NONE
}

An enumeration of the EFR32 power modes.

enum
RAIL_PA_BAND_2P4GIG
RAIL_PA_BAND_SUBGIG
RAIL_PA_BAND_COUNT
}

Enum used to specify the band for a PA.

Typedefs#

typedef int16_t

The transmit power in deci-dBm units (e.g., 4.5 dBm -> 45 deci-dBm).

typedef uint8_t

Raw power levels used directly by the RAIL_Get/SetTxPower API where a higher numerical value corresponds to a higher output power.

typedef uint32_t

PA power setting used directly by the RAIL_GetPaPowerSetting() and RAIL_SetPaPowerSetting() APIs which is decoded to the actual hardware register value(s).

Variables#

The actual PA auto mode configuration structure used by the auto mode plugin to control output power.

Functions#

RAIL_ConfigTxPower(RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t *config)

Initialize TX power settings.

RAIL_GetTxPowerConfig(RAIL_Handle_t railHandle, RAIL_TxPowerConfig_t *config)

Get the TX power settings currently used in the amplifier.

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_GetTxPower(RAIL_Handle_t railHandle)

Return the current power setting of the PA.

RAIL_ConvertRawToDbm(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPowerLevel_t powerLevel)

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

RAIL_ConvertDbmToRaw(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t power)

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

RAIL_VerifyTxPowerCurves(const struct RAIL_TxPowerCurvesConfigAlt *config)

Verify the TX Power Curves on modules.

RAIL_SetTxPowerDbm(RAIL_Handle_t railHandle, RAIL_TxPower_t power)

Set the TX power in terms of deci-dBm instead of raw power level.

RAIL_GetTxPowerDbm(RAIL_Handle_t railHandle)

Get the TX power in terms of deci-dBm instead of raw power level.

RAIL_GetPowerSettingTable(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t *minPower, RAIL_TxPower_t *maxPower, RAIL_TxPowerLevel_t *step)

Get the TX PA power setting table and related values.

RAIL_SetPaPowerSetting(RAIL_Handle_t railHandle, RAIL_PaPowerSetting_t paPowerSetting, RAIL_TxPower_t minPowerDbm, RAIL_TxPower_t maxPowerDbm, RAIL_TxPower_t currentPowerDbm)

Set the TX PA power setting used to configure the PA hardware for the PA output power determined by RAIL_SetTxPowerDbm().

RAIL_GetPaPowerSetting(RAIL_Handle_t railHandle)

Get the TX PA power setting, which is used to configure power configurations when the dBm to paPowerSetting mapping table mode is used.

RAIL_EnablePaAutoMode(RAIL_Handle_t railHandle, bool enable)

Enable automatic switching between PAs internally to the RAIL library.

bool
RAIL_IsPaAutoModeEnabled(RAIL_Handle_t railHandle)

Query status of PA Auto Mode.

RAILCb_PaAutoModeDecision(RAIL_Handle_t railHandle, RAIL_TxPower_t *power, RAIL_TxPowerMode_t *mode, const RAIL_ChannelConfigEntry_t *chCfgEntry)

Callback that decides which PA and power level should be used while in PA auto mode.

RAIL_ConfigPaAutoEntry(RAIL_Handle_t railHandle, const RAIL_PaAutoModeConfigEntry_t *paAutoModeEntry)

Configure the PA auto mode entries.

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_CURVE_DEFAULT_MAX ((RAIL_TxPower_t)200)

The maximum power in deci-dBm the curve supports.

#define

The increment step in deci-dBm for calculating power level.

#define

mV are used for all TX power voltage values.

#define

deci-dBm are used for all TX power dBm values.

#define

Invalid RAIL_TxPowerLevel_t value returned when an error occurs with RAIL_GetTxPower.

#define

Sentinel value that can be passed to RAIL_SetTxPower to set the highest power level available on the current PA, regardless of which one is selected.

#define

Returned by RAIL_GetPaPowerSetting when the device does not support the dBm to power setting mapping table.

#define

The names of the TX power modes.

#define

Convenience macro for any OFDM mapping table mode.

#define

Convenience macro for any Sub-GHz mapping table mode.

#define

Convenience macro for any OFDM mode.

Enumeration Documentation#

RAIL_TxPowerMode_t#

RAIL_TxPowerMode_t

An enumeration of the EFR32 power modes.

The power modes on the EFR32 correspond to the different on-chip PAs that are available. For more information about the power and performance characteristics of a given amplifier, see the data sheet.

Enumerator
RAIL_TX_POWER_MODE_2P4GIG_HP

High-power 2.4 GHz amplifier EFR32xG21: up to 20 dBm, raw values: 1-180 EFR32xG22: up to 6 dBm, raw values: 1-128 EFR32xG24: up to 20 dBm, raw values: 0-180, or up to 10 dBm, raw values: 0-90 EFR32xG26: same as EFR32xG24 EFR32xG27: up to 6 dBm, raw values: 1-128 EFR32xG28: up to 10 dBm, raw values: 0-240 Not supported on other platforms.

RAIL_TX_POWER_MODE_2P4_HP
RAIL_TX_POWER_MODE_2P4GIG_MP

Mid-power 2.4 GHz amplifier EFR32xG21: up to 10 dBm, raw values: 1-90 Not supported on other platforms.

RAIL_TX_POWER_MODE_2P4_MP
RAIL_TX_POWER_MODE_2P4GIG_LP

Low-power 2.4 GHz amplifier EFR32xG21: up to 0 dBm, raw values: 1-64 EFR32xG22: up to 0 dBm, raw values: 1-16 EFR32xG24: up to 0 dBm, raw values: 1-16 EFR32xG26: same as EFR32xG24 EFR32xG27: up to 0 dBm, raw values: 1-16 Not supported on other platforms.

RAIL_TX_POWER_MODE_2P4_LP
RAIL_TX_POWER_MODE_2P4GIG_LLP

Low-Low-power 2.4 GHz amplifier Not currently supported on any EFR32 platform.

RAIL_TX_POWER_MODE_2P4GIG_HIGHEST

Select the highest 2.4 GHz power PA available on the current chip.

RAIL_TX_POWER_MODE_2P4_HIGHEST
RAIL_TX_POWER_MODE_SUBGIG_POWERSETTING_TABLE

PA for all Sub-GHz dBm values in range, using RAIL_PaPowerSetting_t table.

RAIL_TX_POWER_MODE_SUBGIG_HP

High-power Sub-GHz amplifier (Class D mode) Supported on FR32xG23 and EFR32xG28.

RAIL_TX_POWER_MODE_SUBGIG
RAIL_TX_POWER_MODE_SUBGIG_MP

Mid-power Sub-GHz amplifier Supported only on EFR32xG23 and EFR32xG28.

RAIL_TX_POWER_MODE_SUBGIG_LP

Low-power Sub-GHz amplifier Supported only on EFR32xG23 and EFR32xG28.

RAIL_TX_POWER_MODE_SUBGIG_LLP

Low-Low-power Sub-GHz amplifier Supported only on EFR32xG23 and EFR32xG28.

RAIL_TX_POWER_MODE_SUBGIG_HIGHEST

Select the highest Sub-GHz power PA available on the current chip.

RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE

PA for all OFDM Sub-GHz dBm values in range, using RAIL_PaPowerSetting_t table.

RAIL_TX_POWER_MODE_OFDM_PA
RAIL_TX_POWER_MODE_NONE

Invalid amplifier Selection.


Definition at line 1784 of file common/rail_types.h

RAIL_PaBand_t#

RAIL_PaBand_t

Enum used to specify the band for a PA.

Enumerator
RAIL_PA_BAND_2P4GIG

Indicates a 2.4GHz band PA.

RAIL_PA_BAND_SUBGIG

Indicates a Sub-GHz band PA.

RAIL_PA_BAND_COUNT

A count of the choices in this enumeration.


Definition at line 55 of file plugin/pa-auto-mode/pa_auto_mode.h

Typedef Documentation#

RAIL_TxPower_t#

typedef int16_t RAIL_TxPower_t

The transmit power in deci-dBm units (e.g., 4.5 dBm -> 45 deci-dBm).

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


Definition at line 1718 of file common/rail_types.h

RAIL_TxPowerLevel_t#

typedef uint8_t RAIL_TxPowerLevel_t

Raw power levels used directly by the RAIL_Get/SetTxPower API where a higher numerical value corresponds to a higher output power.

These are referred to as 'raw (values/units)'. On EFR32, they can range from one of RAIL_TX_POWER_LEVEL_2P4_LP_MIN, RAIL_TX_POWER_LEVEL_2P4_HP_MIN, or RAIL_TX_POWER_LEVEL_SUBGIG_HP_MIN to one of RAIL_TX_POWER_LEVEL_2P4_LP_MAX, RAIL_TX_POWER_LEVEL_2P4_HP_MAX, and RAIL_TX_POWER_LEVEL_SUBGIG_HP_MAX, respectively, depending on the selected RAIL_TxPowerMode_t.


Definition at line 1748 of file common/rail_types.h

RAIL_PaPowerSetting_t#

typedef uint32_t RAIL_PaPowerSetting_t

PA power setting used directly by the RAIL_GetPaPowerSetting() and RAIL_SetPaPowerSetting() APIs which is decoded to the actual hardware register value(s).


Definition at line 1768 of file common/rail_types.h

Variable Documentation#

RAIL_PaAutoModeConfig#

const RAIL_PaAutoModeConfigEntry_t* RAIL_PaAutoModeConfig

The actual PA auto mode configuration structure used by the auto mode plugin to control output power.


Definition at line 91 of file plugin/pa-auto-mode/pa_auto_mode.h

Function Documentation#

RAIL_ConfigTxPower#

RAIL_Status_t RAIL_ConfigTxPower (RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t *config)

Initialize TX power settings.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A pointer to apower config with the desired initial settings for the TX amplifier.

Returns

  • Status code indicating success of the function call.

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 this function should always be called during initialization, it can also be called any time if these settings need to change to adapt to a different application/protocol. This API also resets TX power to RAIL_TX_POWER_LEVEL_INVALID, so RAIL_SetTxPower must be called afterwards.

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. A change in RAIL_TxPowerConfig_t::rampTime may affect the minimum timings that can be achieved in RAIL_StateTiming_t::idleToTx and RAIL_StateTiming_t::rxToTx. Call RAIL_SetStateTiming() again to check whether these times have changed.


Definition at line 2717 of file common/rail.h

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]railHandle

A RAIL instance handle.

[out]config

A pointer to memory allocated to hold the current TxPower configuration structure. A NULL configuration will produce undefined behavior.

Returns

  • Status code indicating success of the function call.

Note that this API does not return the current TX power, which is separately managed by the RAIL_GetTxPower / RAIL_SetTxPower APIs. Use this API to determine which values were set as a result of RAIL_ConfigTxPower.


Definition at line 2734 of file common/rail.h

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]railHandle

A RAIL instance handle.

[in]powerLevel

Power in radio-specific RAIL_TxPowerLevel_t units.

Returns

  • Status code indicating success of the function call.

To convert between decibels and the integer values that the registers take, call RAIL_ConvertDbmToRaw. A weak version of this function, which works well with our boards is provided. However, customers using a custom board need to characterize radio operation on that board and override the function to convert 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 return an error.


Definition at line 2760 of file common/rail.h

RAIL_GetTxPower#

RAIL_TxPowerLevel_t RAIL_GetTxPower (RAIL_Handle_t railHandle)

Return the current power setting of the PA.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

This API returns the raw value that was set by RAIL_SetTxPower. A weak version of RAIL_ConvertRawToDbm that works with Silicon Labs boards to convert the raw values into actual output dBm values is provided. However, customers using a custom board need to re-characterize the relationship between raw and decibel values and rewrite the provided function.

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


Definition at line 2781 of file common/rail.h

RAIL_ConvertRawToDbm#

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

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

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

PA mode for which to convert.

[in]powerLevel

A raw 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 that is tuned to provide accurate values for our boards. For 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 okay to use either a real protocol handle, or one of the radio-generic ones, such as RAIL_EFR32_HANDLE.

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


Definition at line 2807 of file common/rail.h

RAIL_ConvertDbmToRaw#

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

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

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

PA mode for which to do the conversion.

[in]power

Desired 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 that is tuned to provide accurate values for our boards. For 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 okay to use either a real protocol handle, or one of the radio-generic ones, such as RAIL_EFR32_HANDLE.

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


Definition at line 2835 of file common/rail.h

RAIL_VerifyTxPowerCurves#

RAIL_Status_t RAIL_VerifyTxPowerCurves (const struct RAIL_TxPowerCurvesConfigAlt *config)

Verify the TX Power Curves on modules.

Parameters
[in]config

A pointer to TX Power Curves to use on this module.

Returns

  • Status code indicating success of function call.

This function only needs to be called when using a module and has no effect otherwise. Transmit will not work before this function is called.


Definition at line 2847 of file common/rail.h

RAIL_SetTxPowerDbm#

RAIL_Status_t RAIL_SetTxPowerDbm (RAIL_Handle_t railHandle, RAIL_TxPower_t power)

Set the TX power in terms of deci-dBm instead of raw power level.

Parameters
[in]railHandle

A RAIL instance handle.

[in]power

A desired deci-dBm power to be set.

Returns

  • Status code indicating success of the function call.

This is a utility function for user convenience. Normally, to set TX power in dBm, do the following:

RAIL_TxPower_t power = 100; // 100 deci-dBm, 10 dBm
RAIL_TxPowerConfig_t txPowerConfig;
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);
RAIL_SetTxPower(railHandle, powerLevel);

This function wraps all those calls in a single function with power passed in as a parameter.


Definition at line 2872 of file common/rail.h

RAIL_GetTxPowerDbm#

RAIL_TxPower_t RAIL_GetTxPowerDbm (RAIL_Handle_t railHandle)

Get the TX power in terms of deci-dBm instead of raw power level.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The current output power in deci-dBm.

This is a utility function for user convenience. Normally, to get TX power in dBm, do the following:

RAIL_TxPowerLevel_t powerLevel = RAIL_GetTxPower(railHandle);
RAIL_TxPowerConfig_t txPowerConfig;
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);
// RAIL_ConvertRawToDbm will be the weak version provided by Silicon Labs
// by default, or the customer version, if overwritten.
RAIL_TxPower_t power = RAIL_ConvertRawToDbm(railHandle,
                                            txPowerConfig.mode,
                                            powerLevel);
return power;

This function wraps all those calls in a single function with power returned as the result.


Definition at line 2897 of file common/rail.h

RAIL_GetPowerSettingTable#

const RAIL_PaPowerSetting_t * RAIL_GetPowerSettingTable (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t *minPower, RAIL_TxPower_t *maxPower, RAIL_TxPowerLevel_t *step)

Get the TX PA power setting table and related values.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

PA mode for which to get the powersetting table.

[out]minPower

A pointer to a RAIL_TxPower_t.

[out]maxPower

A pointer to a RAIL_TxPower_t.

[out]step

A pointer to a RAIL_TxPowerLevel_t, but in deci-dBm units.

Returns

  • Power setting table start address. When NULL is returned all out params above won't be set.

The number of entries in the table can be calculated based on output minPower, maxPower, and step parameters. For example, for minPower = 115 (11.5 dBm), maxPower = 300 (30 dBm), and step = 1 (0.1 dBm), the number of entries in table would be 186.


Definition at line 2915 of file common/rail.h

RAIL_SetPaPowerSetting#

RAIL_Status_t RAIL_SetPaPowerSetting (RAIL_Handle_t railHandle, RAIL_PaPowerSetting_t paPowerSetting, RAIL_TxPower_t minPowerDbm, RAIL_TxPower_t maxPowerDbm, RAIL_TxPower_t currentPowerDbm)

Set the TX PA power setting used to configure the PA hardware for the PA output power determined by RAIL_SetTxPowerDbm().

Parameters
[in]railHandle

A RAIL instance handle.

[in]paPowerSetting

The desired PA power setting.

[in]minPowerDbm

The minimum power in dBm that the PA can output.

[in]maxPowerDbm

The maximum power in dBm that the PA can output.

[in]currentPowerDbm

The corresponding output power in dBm for this power setting.

Returns

  • Status code indicating success of the function call.


Definition at line 2930 of file common/rail.h

RAIL_GetPaPowerSetting#

RAIL_PaPowerSetting_t RAIL_GetPaPowerSetting (RAIL_Handle_t railHandle)

Get the TX PA power setting, which is used to configure power configurations when the dBm to paPowerSetting mapping table mode is used.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The current PA power setting.


Definition at line 2943 of file common/rail.h

RAIL_EnablePaAutoMode#

RAIL_Status_t RAIL_EnablePaAutoMode (RAIL_Handle_t railHandle, bool enable)

Enable automatic switching between PAs internally to the RAIL library.

Parameters
[in]railHandle

A real RAIL instance handle.

[in]enable

Enable or disable PA Auto Mode.

Returns

  • Status code indicating success of the function call.

While PA Automode is enabled, the PA will be chosen and set automatically whenever RAIL_SetTxPowerDbm is called or whenever powers are coerced automatically, internally to the RAIL library during a channel change. While PA Auto Mode is enabled, users cannot call RAIL_ConfigTxPower or RAIL_SetTxPower. When entering auto mode, RAIL_SetTxPowerDbm must be called to specify the desired power. When leaving auto mode, RAIL_ConfigTxPower as well as one of RAIL_SetTxPower or RAIL_SetTxPowerDbm must be called to re-specify the desired PA and power level combination.

Note

  • : Power conversion curves must be initialized before calling this function. That is, RAIL_ConvertDbmToRaw and RAIL_ConvertRawToDbm most both be able to operate properly to ensure that PA Auto Mode functions correctly. See the PA Conversions plugin or AN1127 for more details.


Definition at line 2967 of file common/rail.h

RAIL_IsPaAutoModeEnabled#

bool RAIL_IsPaAutoModeEnabled (RAIL_Handle_t railHandle)

Query status of PA Auto Mode.

Parameters
[in]railHandle

A real RAIL instance handle.

Returns

  • Indicator of whether Auto Mode is enabled (true) or not (false).


Definition at line 2975 of file common/rail.h

RAILCb_PaAutoModeDecision#

RAIL_Status_t RAILCb_PaAutoModeDecision (RAIL_Handle_t railHandle, RAIL_TxPower_t *power, RAIL_TxPowerMode_t *mode, const RAIL_ChannelConfigEntry_t *chCfgEntry)

Callback that decides which PA and power level should be used while in PA auto mode.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]power

A pointer to the dBm output power (in deci-dBm, 10*dBm) being requested. The value this points to when the function returns will be applied to the radio.

[out]mode

A pointer to the RAIL_TxPowerMode_t to be used to achieve the requested power. The value this points to when the function returns will be applied to the radio.

[in]chCfgEntry

A pointer to a RAIL_ChannelConfigEntry_t. While switching channels, it will be the entry RAIL is switch to, during a call to RAIL_SetTxPowerDbm, it will be the entry RAIL is already on. Can be NULL if a channel configuration was not set or no valid channels are present.

Returns

  • Status code indicating success of the function call. If this is anything except RAIL_STATUS_NO_ERROR, neither PA's nor their powers will be configured automatically.

Whatever values mode and powerLevel point to when this function return will be applied to the PA hardware and used for transmits.

Note

  • The mode and power level provided by this function depends on the RAIL_PaAutoModeConfig provided for the radio. The RAIL_PaAutoModeConfig definition for a radio should tend to all the bands supported by the radio and cover the full range of power to find a valid entry for requested power for a specific band.


Definition at line 3006 of file common/rail.h

RAIL_ConfigPaAutoEntry#

RAIL_Status_t RAIL_ConfigPaAutoEntry (RAIL_Handle_t railHandle, const RAIL_PaAutoModeConfigEntry_t *paAutoModeEntry)

Configure the PA auto mode entries.

Parameters
[in]railHandle

A RAIL instance handle.

[in]paAutoModeEntry

Entries used to configure PA auto mode decision points.

Returns

  • Status parameter indicating success of function call.


Definition at line 100 of file plugin/pa-auto-mode/pa_auto_mode.h

Macro Definition Documentation#

RAIL_TX_POWER_MAX#

#define RAIL_TX_POWER_MAX
Value:
((RAIL_TxPower_t)0x7FFF)

The maximum valid value for a RAIL_TxPower_t.


Definition at line 1721 of file common/rail_types.h

RAIL_TX_POWER_MIN#

#define RAIL_TX_POWER_MIN
Value:
((RAIL_TxPower_t)0x8000)

The minimum valid value for a RAIL_TxPower_t.


Definition at line 1723 of file common/rail_types.h

RAIL_TX_POWER_CURVE_DEFAULT_MAX#

#define RAIL_TX_POWER_CURVE_DEFAULT_MAX
Value:
((RAIL_TxPower_t)200)

The maximum power in deci-dBm the curve supports.


Definition at line 1726 of file common/rail_types.h

RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT#

#define RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT
Value:
((RAIL_TxPower_t)40)

The increment step in deci-dBm for calculating power level.


Definition at line 1728 of file common/rail_types.h

RAIL_TX_POWER_VOLTAGE_SCALING_FACTOR#

#define RAIL_TX_POWER_VOLTAGE_SCALING_FACTOR
Value:
1000

mV are used for all TX power voltage values.

TX power voltages take and return voltages multiplied by this factor.


Definition at line 1732 of file common/rail_types.h

RAIL_TX_POWER_DBM_SCALING_FACTOR#

#define RAIL_TX_POWER_DBM_SCALING_FACTOR
Value:
10

deci-dBm are used for all TX power dBm values.

All dBm inputs to TX power functions take dBm power times this factor.


Definition at line 1736 of file common/rail_types.h

RAIL_TX_POWER_LEVEL_INVALID#

#define RAIL_TX_POWER_LEVEL_INVALID
Value:
(255U)

Invalid RAIL_TxPowerLevel_t value returned when an error occurs with RAIL_GetTxPower.


Definition at line 1754 of file common/rail_types.h

RAIL_TX_POWER_LEVEL_MAX#

#define RAIL_TX_POWER_LEVEL_MAX
Value:
(254U)

Sentinel value that can be passed to RAIL_SetTxPower to set the highest power level available on the current PA, regardless of which one is selected.


Definition at line 1761 of file common/rail_types.h

RAIL_TX_PA_POWER_SETTING_UNSUPPORTED#

#define RAIL_TX_PA_POWER_SETTING_UNSUPPORTED
Value:
(0U)

Returned by RAIL_GetPaPowerSetting when the device does not support the dBm to power setting mapping table.


Definition at line 1774 of file common/rail_types.h

RAIL_TX_POWER_MODE_NAMES#

#define RAIL_TX_POWER_MODE_NAMES
Value:
{ \
"RAIL_TX_POWER_MODE_2P4GIG_HP", \
"RAIL_TX_POWER_MODE_2P4GIG_MP", \
"RAIL_TX_POWER_MODE_2P4GIG_LP", \
"RAIL_TX_POWER_MODE_2P4GIG_LLP", \
"RAIL_TX_POWER_MODE_2P4GIG_HIGHEST", \
"RAIL_TX_POWER_MODE_SUBGIG_POWERSETTING_TABLE", \
"RAIL_TX_POWER_MODE_SUBGIG_HP", \
"RAIL_TX_POWER_MODE_SUBGIG_MP", \
"RAIL_TX_POWER_MODE_SUBGIG_LP", \
"RAIL_TX_POWER_MODE_SUBGIG_LLP", \
"RAIL_TX_POWER_MODE_SUBGIG_HIGHEST", \
"RAIL_TX_POWER_MODE_OFDM_PA_POWERSETTING_TABLE", \
"RAIL_TX_POWER_MODE_NONE" \
}

The names of the TX power modes.

A list of the names for the TX power modes on EFR32 parts. This macro is useful for test applications and debugging output.


Definition at line 1898 of file common/rail_types.h

RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_OFDM#

#define RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_OFDM
Value:
(x)

Convenience macro for any OFDM mapping table mode.


Definition at line 1933 of file common/rail_types.h

RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_SUBGIG#

#define RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_SUBGIG
Value:
(x)

Convenience macro for any Sub-GHz mapping table mode.


Definition at line 1936 of file common/rail_types.h

RAIL_POWER_MODE_IS_ANY_OFDM#

#define RAIL_POWER_MODE_IS_ANY_OFDM
Value:
(x)

Convenience macro for any OFDM mode.


Definition at line 1939 of file common/rail_types.h