Modules#

EFR32

Calibration#

APIs for calibrating the radio.

These APIs 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 the following:

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);
    }
  }
}

Typedefs#

typedef uint32_t

A calibration mask type.

Functions#

RAIL_ConfigCal(RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)

Initialize RAIL calibration.

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

Start the calibration process.

RAIL_GetPendingCal(RAIL_Handle_t railHandle)

Return the current set of pending calibrations.

void
RAIL_EnablePaCal(bool enable)

Enable/disable the PA calibration.

Macros#

#define

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

Typedef Documentation#

RAIL_CalMask_t#

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 3719 of file common/rail_types.h

Function Documentation#

RAIL_ConfigCal#

RAIL_Status_t RAIL_ConfigCal (RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)

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


Definition at line 4680 of file common/rail.h

RAIL_Calibrate#

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

Start the calibration process.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]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 make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, to perform an IR calibration for the first time, it will return RAIL_STATUS_INVALID_STATE, in which case the application must defer calibration until after the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.

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.


Definition at line 4726 of file common/rail.h

RAIL_GetPendingCal#

RAIL_CalMask_t RAIL_GetPendingCal (RAIL_Handle_t railHandle)

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


Definition at line 4741 of file common/rail.h

RAIL_EnablePaCal#

void RAIL_EnablePaCal (bool enable)

Enable/disable the PA calibration.

Parameters
[in]enable

Enables/disables the PA calibration.

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

Note


Definition at line 4754 of file common/rail.h

Macro Definition Documentation#

RAIL_PACTUNE_IGNORE#

#define RAIL_PACTUNE_IGNORE
Value:
(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 936 of file chip/efr32/efr32xg1x/rail_chip_specific.h