Power Amplifier (PA)#

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.

RAIL_PaBand_t#

RAIL_PaBand_t

Enum used to specify the band for a PA.

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.

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.

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

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.

RAIL_ConfigTxPower#

RAIL_Status_t RAIL_ConfigTxPower (RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t * config)

Initialize TX power settings.

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

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.

Returns

• RAIL status variable indicating whether or not the get was successful.

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.

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

Returns

• RAIL_Status_t indicating success or an error.

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 chip 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.

RAIL_GetTxPower#

RAIL_TxPowerLevel_t RAIL_GetTxPower (RAIL_Handle_t railHandle)

Return the current power setting of the PA.

Returns

• The chip-specific RAIL_TxPowerLevel_t value of the current transmit power.

This API returns the raw value that was set by RAIL_SetTxPower. A weak version of RAIL_ConvertRawToDbm that works with our 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).

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

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 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_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.

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 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 the assert, ensure that the maxPower of all channel configuration entries is RAIL_TX_POWER_MAX or above, or override this function to always return 255.

RAIL_VerifyTxPowerCurves#

void RAIL_VerifyTxPowerCurves (const struct RAIL_TxPowerCurvesConfigAlt * config)

Verify the TX Power Curves on modules.

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.

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.

Returns

• RAIL Status variable indicate whether setting the power was successful.

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.

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.

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.

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.

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 the minPower, maxPower, and step parameters. For example, for minPower = 115 (11.5 dBm), maxPower = 300 (30 dBm), and step = 1, the number of entries in table would be 186

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

Returns

• RAIL Status variable indicate whether setting the PA power setting was successful.

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.

Returns

• The current PA power setting.

RAIL_EnablePaAutoMode#

RAIL_Status_t RAIL_EnablePaAutoMode (RAIL_Handle_t railHandle, bool enable)

Enable automatic switching between PAs internally to the RAIL library.

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.

Returns

• Status parameter indicating success of function call.

RAIL_IsPaAutoModeEnabled#

bool RAIL_IsPaAutoModeEnabled (RAIL_Handle_t railHandle)

Query status of PA Auto Mode.

Returns

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

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.

Returns

• Return status indicating result of 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 chip. The RAIL_PaAutoModeConfig definition for a chip should tend to all the bands supported by the chip and cover the full range of power to find a valid entry for requested power for a specific band.

RAIL_ConfigPaAutoEntry#

RAIL_Status_t RAIL_ConfigPaAutoEntry (RAIL_Handle_t railHandle, const RAIL_PaAutoModeConfigEntry_t * paAutoModeEntry)

Configure the PA auto mode entries.

Returns

• Status parameter indicating success of function call.

RAIL_TX_POWER_MAX#

#define RAIL_TX_POWER_MAX

((RAIL_TxPower_t)0x7FFF)

The maximum valid value for a RAIL_TxPower_t.

RAIL_TX_POWER_MIN#

#define RAIL_TX_POWER_MIN

((RAIL_TxPower_t)0x8000)

The minimum valid value for a RAIL_TxPower_t.

RAIL_TX_POWER_CURVE_DEFAULT_MAX#

#define RAIL_TX_POWER_CURVE_DEFAULT_MAX

((RAIL_TxPower_t)200)

The maximum power in deci-dBm the curve supports.

RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT#

#define RAIL_TX_POWER_CURVE_DEFAULT_INCREMENT

((RAIL_TxPower_t)40)

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

RAIL_TX_POWER_VOLTAGE_SCALING_FACTOR#

#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.

RAIL_TX_POWER_DBM_SCALING_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.

RAIL_TX_POWER_LEVEL_INVALID#

#define RAIL_TX_POWER_LEVEL_INVALID

(255U)

Invalid RAIL_TxPowerLevel_t value returned when an error occurs with RAIL_GetTxPower.

RAIL_TX_POWER_LEVEL_MAX#

#define RAIL_TX_POWER_LEVEL_MAX

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

RAIL_TX_PA_POWER_SETTING_UNSUPPORTED#

#define RAIL_TX_PA_POWER_SETTING_UNSUPPORTED

(0U)

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

RAIL_TX_POWER_MODE_NAMES#

#define RAIL_TX_POWER_MODE_NAMES

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.

RAIL_POWER_MODE_IS_ANY_EFF#

#define RAIL_POWER_MODE_IS_ANY_EFF

Convenience macro for any EFF power mode.

RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_OFDM#

#define RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_OFDM

Convenience macro for any OFDM mapping table mode.

RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_SUBGIG#

#define RAIL_POWER_MODE_IS_DBM_POWERSETTING_MAPPING_TABLE_SUBGIG

Convenience macro for any Sub-GHz mapping table mode.

RAIL_POWER_MODE_IS_ANY_DBM_POWERSETTING_MAPPING_TABLE#

#define RAIL_POWER_MODE_IS_ANY_DBM_POWERSETTING_MAPPING_TABLE

Convenience macro for any mapping table mode.

RAIL_POWER_MODE_IS_ANY_OFDM#

#define RAIL_POWER_MODE_IS_ANY_OFDM

(x)

Convenience macro for any OFDM mode.