Calibration
RAIL API

APIs for calibrating the radio.

Modules

EFR32
EFR32-specific CalibrationsThe EFR32 supports the Image Rejection (IR) calibration and a temperature-dependent calibration.

Macros

#define RAIL_PACTUNE_IGNORE (255U)
Use this value with either TX or RX values in RAIL_SetPaCTune to use whatever value is already set and do no update.

Typedefs

typedef uint32_t RAIL_CalMask_t
A calibration mask type.

Functions

RAIL_Status_t RAIL_ConfigCal ( RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)
Initializes RAIL calibration.
RAIL_Status_t RAIL_Calibrate ( RAIL_Handle_t railHandle, RAIL_CalValues_t *calValues, RAIL_CalMask_t calForce)
Starts the calibration process.
RAIL_CalMask_t RAIL_GetPendingCal ( RAIL_Handle_t railHandle)
Returns the current set of pending calibrations.
void RAIL_EnablePaCal (bool enable)
Enables/disables the PA calibration.

Detailed Description

APIs for calibrating the radio.

These APIs can be used to calibrate the radio. The RAIL library determines which calibrations are necessary. Calibrations can be enabled/disabled with the RAIL_CalMask_t parameter.

Some calibrations produce values that can be saved and reapplied to avoid repeating the calibration process.

Calibrations can either be run with RAIL_Calibrate , or with the individual chip-specific calibration routines. An example for running code with RAIL_Calibrate looks like:

static RAIL_CalValues_t calValues = RAIL_CALVALUES_UNINIT ;
void RAILCb_Event( RAIL_Handle_t railHandle, RAIL_Events_t events) {
// Omitting other event handlers
if (events & RAIL_EVENT_CAL_NEEDED ) {
// Run all pending calibrations, and save the results
RAIL_Calibrate (railHandle, &calValues, RAIL_CAL_ALL_PENDING );
}
}

Alternatively, if the image rejection calibration for your chip can be determined ahead of time, such as by running the calibration on a separate firmware image on each chip, the following calibration process will result in smaller code.

static uint32_t imageRejection = IRCAL_VALUE;
void RAILCb_Event( RAIL_Handle_t railHandle, RAIL_Events_t events) {
// Omitting other event handlers
if (events & RAIL_EVENT_CAL_NEEDED ) {
RAIL_CalMask_t pendingCals = RAIL_GetPendingCal (railHandle);
// Disable the radio if we have to do an offline calibration
if (pendingCals & RAIL_CAL_TEMP_VC0) {
RAIL_CalibrateTemp (railHandle);
}
if (pendingCals & RAIL_CAL_ONETIME_IRCAL ) {
RAIL_ApplyIrCalibration (railHandle, imageRejection);
}
}
}

Macro Definition Documentation

#define RAIL_PACTUNE_IGNORE   (255U)

Use this value with either TX or RX values in RAIL_SetPaCTune to use whatever value is already set and do no update.

Definition at line 684 of file rail_chip_specific.h .

Typedef Documentation

RAIL_CalMask_t

A calibration mask type.

This type is a bitmask of different RAIL calibration values. The exact meaning of these bits depends on what a particular chip supports.

Definition at line 2482 of file rail_types.h .

Function Documentation

RAIL_Status_t RAIL_Calibrate ( RAIL_Handle_t railHandle,
RAIL_CalValues_t * calValues,
RAIL_CalMask_t calForce
)

Starts the calibration process.

Parameters
[in] railHandle A RAIL instance handle.
[in,out] calValues A structure of calibration values to apply. If a valid calibration structure is provided and the structure contains valid calibration values, those values will be applied to the hardware and the RAIL library will cache those values for use again later. If a valid calibration structure is provided and the structure contains a calibration value of RAIL_CAL_INVALID_VALUE for the desired calibration, the desired calibration will run, the calibration values structure will be updated with a valid calibration value, and the RAIL library will cache that value for use again later. If a NULL pointer is provided, the desired calibration will run and the RAIL library will cache that value for use again later. However, the valid calibration value will not be returned to the application.
[in] calForce A mask to force specific calibration(s) to execute. To run all pending calibrations, use the value RAIL_CAL_ALL_PENDING . Only the calibrations specified will run, even if not enabled during initialization.
Returns
Status code indicating success of the function call.

If calibrations were performed previously and the application saves the calibration values (i.e., call this function with a calibration values structure containing calibration values of RAIL_CAL_INVALID_VALUE before a reset), the application can later bypass the time it would normally take to recalibrate hardware by reusing previous calibration values (i.e., call this function with a calibration values structure containing valid calibration values after a reset).

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. The caller must attempt to re-call this function later.

Note
Instead of this function, consider using the individual chip-specific functions. Using the individual functions will allow for better dead-stripping if not all calibrations are run.
Some calibrations should only be executed when the radio is IDLE. See chip-specific documentation for more details.
RAIL_Status_t RAIL_ConfigCal ( RAIL_Handle_t railHandle,
RAIL_CalMask_t calEnable
)

Initializes RAIL calibration.

Parameters
[in] railHandle A RAIL instance handle.
[in] calEnable A bitmask that indicates which calibrations to enable for a callback notification. The exact meaning of these bits is chip-specific.
Returns
Status code indicating success of the function call.

Calibration initialization provides the calibration settings that correspond to the current radio configuration.

void RAIL_EnablePaCal ( bool enable )

Enables/disables the PA calibration.

Parameters
[in] enable Enables/disables the PA calibration.
Returns
void.

Enabling will ensure that the PA power remains constant chip-to-chip. By default, this feature is disabled after reset.

Note
This function should be called before RAIL_ConfigTxPower() if this feature is desired.
RAIL_CalMask_t RAIL_GetPendingCal ( RAIL_Handle_t railHandle )

Returns the current set of pending calibrations.

Parameters
[in] railHandle A RAIL instance handle.
Returns
A mask of all pending calibrations that the user has been asked to perform.

This function returns a full set of pending calibrations. The only way to clear pending calibrations is to perform them using the RAIL_Calibrate() API with the appropriate list of calibrations.