Calibration#

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.

RAIL_RxIrCalValues_t#

typedef uint32_t RAIL_RxIrCalValues_t[2] [2]

RAIL_RxIrCalValues_t.

RX IR calibration values.

Platforms with fewer RAIL_RF_PATHS than RAIL_MAX_RF_PATHS will only respect and update RAIL_RF_PATHS indices and ignore the rest.

RAIL_CalValues_t#

RAIL_CalValues_t

A calibration value structure.

This structure contains the set of persistent calibration values for EFR32. You can set these beforehand and apply them at startup to save the time required to compute them. Any of these values may be set to RAIL_CAL_INVALID_VALUE to force the code to compute that calibration value.

RAIL_ConfigCal#

RAIL_Status_t RAIL_ConfigCal (RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)

Initialize RAIL calibration.

Returns

• Status code indicating success of the function call.

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

RAIL_Calibrate#

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

Start the calibration process.

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.

RAIL_GetPendingCal#

RAIL_CalMask_t RAIL_GetPendingCal (RAIL_Handle_t railHandle)

Return the current set of pending calibrations.

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.

RAIL_ApplyIrCalibration#

RAIL_Status_t RAIL_ApplyIrCalibration (RAIL_Handle_t railHandle, uint32_t imageRejection)

Apply a given image rejection calibration value.

Returns

• A status code indicating success of the function call.

Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIr on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.

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

DeprecatedPlease use RAIL_ApplyIrCalibrationAlt instead.

RAIL_ApplyIrCalibrationAlt#

RAIL_Status_t RAIL_ApplyIrCalibrationAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Apply a given image rejection calibration value.

Returns

• A status code indicating success of the function call.

Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIrAlt on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. Note

• : To make sure the imageRejection value is stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.

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

RAIL_CalibrateIr#

RAIL_Status_t RAIL_CalibrateIr (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Run the image rejection calibration.

Returns

• A status code indicating success of the function call.

Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image.

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, it will return RAIL_STATUS_INVALID_STATE. In this case, RAIL_ApplyIrCalibration may be called to apply a previously determined IR calibration value, or the app must defer calibration until the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.

DeprecatedPlease use RAIL_CalibrateIrAlt instead.

RAIL_CalibrateIrAlt#

RAIL_Status_t RAIL_CalibrateIrAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Run the image rejection calibration.

Returns

• A status code indicating success of the function call.

Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image. Note

• : To make sure the imageRejection value is stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.

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

RAIL_CalibrateTemp#

RAIL_Status_t RAIL_CalibrateTemp (RAIL_Handle_t railHandle)

Run the temperature calibration.

Returns

• A status code indicating success of the function call.

Run the temperature calibration, which needs to recalibrate the synth if the temperature crosses 0C or the temperature delta since the last calibration exceeds 70C while in receive. RAIL will run the VCO calibration automatically upon entering receive or transmit states, so the application can omit this calibration if the stack re-enters receive or transmit with enough frequency to avoid reaching the temperature delta. If the application does not calibrate for temperature, it's possible to miss receive packets due to a drift in the carrier frequency.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the calibration will be automatically performed next time the radio enters receive.

RAIL_CalibrateHFXO#

RAIL_Status_t RAIL_CalibrateHFXO (RAIL_Handle_t railHandle, int8_t *crystalPPMError)

Performs HFXO compensation.

Returns

• A status code indicating the result of the function call.

Compute the PPM correction using the thermistor value available when RAIL_EVENT_THERMISTOR_DONE occurs, after RAIL_StartThermistorMeasurement() call. Then correct the RF frequency as well as TX and RX sampling.

This function calls the following RAIL functions in sequence saving having to call them individually:

• RAIL_ConvertThermistorImpedance()

• RAIL_ComputeHFXOPPMError()

• RAIL_CompensateHFXO()

Note

• This function makes the radio idle.

RAIL_EnablePaCal#

void RAIL_EnablePaCal (bool enable)

Enable/disable the PA calibration.

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

Note

• Call this function before RAIL_ConfigTxPower() if this feature is desired.

RAIL_BLE_CalibrateIr#

RAIL_Status_t RAIL_BLE_CalibrateIr (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for Bluetooth Low Energy.

Returns

• A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.

RAIL_IEEE802154_CalibrateIr2p4Ghz#

RAIL_Status_t RAIL_IEEE802154_CalibrateIr2p4Ghz (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for IEEE 802.15.4 2.4 GHz.

Returns

• A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.

RAIL_IEEE802154_CalibrateIrSubGhz#

RAIL_Status_t RAIL_IEEE802154_CalibrateIrSubGhz (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for IEEE 802.15.4 915 MHz and 868 MHz.

Returns

• A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.

DeprecatedPlease use RAIL_CalibrateIrAlt instead.

RAIL_CAL_TEMP_VCO#

#define RAIL_CAL_TEMP_VCO

(0x00000001U)

EFR32-specific temperature calibration bit.

RAIL_CAL_TEMP_HFXO#

#define RAIL_CAL_TEMP_HFXO

(0x00000002U)

EFR32-specific HFXO temperature check bit.

(Ignored if platform lacks RAIL_SUPPORTS_HFXO_COMPENSATION.)

RAIL_CAL_COMPENSATE_HFXO#

#define RAIL_CAL_COMPENSATE_HFXO

(0x00000004U)

EFR32-specific HFXO compensation bit.

(Ignored if platform lacks RAIL_SUPPORTS_HFXO_COMPENSATION.)

RAIL_CAL_RX_IRCAL#

#define RAIL_CAL_RX_IRCAL

(0x00010000U)

EFR32-specific IR calibration bit.

RAIL_CAL_OFDM_TX_IRCAL#

#define RAIL_CAL_OFDM_TX_IRCAL

(0x00100000U)

EFR32-specific Tx IR calibration bit.

(Ignored if platform lacks RAIL_SUPPORTS_OFDM_PA.)

RAIL_CAL_ONETIME_IRCAL#

#define RAIL_CAL_ONETIME_IRCAL

(RAIL_CAL_RX_IRCAL | RAIL_CAL_OFDM_TX_IRCAL)

A mask to run EFR32-specific IR calibrations.

RAIL_CAL_TEMP#

#define RAIL_CAL_TEMP

(RAIL_CAL_TEMP_VCO | RAIL_CAL_TEMP_HFXO | RAIL_CAL_COMPENSATE_HFXO)

A mask to run temperature-dependent calibrations.

RAIL_CAL_ONETIME#

#define RAIL_CAL_ONETIME

(RAIL_CAL_ONETIME_IRCAL)

A mask to run one-time calibrations.

RAIL_CAL_PERF#

#define RAIL_CAL_PERF

(0)

A mask to run optional performance calibrations.

RAIL_CAL_OFFLINE#

#define RAIL_CAL_OFFLINE

(RAIL_CAL_ONETIME_IRCAL)

A mask for calibrations that require the radio to be off.

RAIL_CAL_ALL#

#define RAIL_CAL_ALL

(RAIL_CAL_TEMP | RAIL_CAL_ONETIME)

A mask to run all possible calibrations for this chip.

RAIL_CAL_ALL_PENDING#

#define RAIL_CAL_ALL_PENDING

(0x00000000U)

A mask to run all pending calibrations.

RAIL_CAL_INVALID_VALUE#

#define RAIL_CAL_INVALID_VALUE

(0xFFFFFFFFU)

An invalid calibration value.

RAIL_MAX_RF_PATHS#

#define RAIL_MAX_RF_PATHS

2

Indicates the maximum number of RF Paths supported across all platforms.

RAIL_IRCALVALUES_RX_UNINIT#

#define RAIL_IRCALVALUES_RX_UNINIT

A define to set all RAIL_RxIrCalValues_t values to uninitialized.

This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.

RAIL_IRCALVALUES_TX_UNINIT#

#define RAIL_IRCALVALUES_TX_UNINIT

A define to set all RAIL_TxIrCalValues_t values to uninitialized.

This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.

RAIL_IRCALVALUES_UNINIT#

#define RAIL_IRCALVALUES_UNINIT

A define to set all RAIL_IrCalValues_t values to uninitialized.

This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.

RAIL_IRCALVAL#

#define RAIL_IRCALVAL

(irCalStruct, rfPath)

A define allowing Rx calibration value access compatibility between non-OFDM and OFDM platforms.

RAIL_CALVALUES_UNINIT#

#define RAIL_CALVALUES_UNINIT

RAIL_IRCALVALUES_UNINIT

A define to set all RAIL_CalValues_t values to uninitialized.

This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.

RAIL_PACTUNE_IGNORE#

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

This value is provided to provide consistency across EFR32 chips, but technically speaking, all PA capacitance tuning values are invalid on EFR32XG21 parts, as RAIL_SetPaCTune is not supported on those parts.